/ Hex Artifact Content
Login

Artifact ecbd714ecc0ff710a149fc72db6552738148ad0c:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64  ust not close [d
3e90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3ea0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
3eb0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3ee0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3ef0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3f00: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f10: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
3f20: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
3f30: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
3f40: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
3f50: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f60: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
3f70: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3f80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3f90: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
3fa0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
3fb0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
3ff0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
4000: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
4030: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4040: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4050: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4060: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4070: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4080: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
40c0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
40d0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4100: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
4110: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
4120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
4130: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4140: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
4150: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
4160: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4170: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4180: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
4190: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
41a0: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
41b0: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
41c0: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
41d0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
41e0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
41f0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
4200: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
4210: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
4220: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4230: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4240: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4250: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4260: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
4270: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
4280: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4290: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  ],.** [sqlite3_v
42a0: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
42b0: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42  )] [SQLITE_ROLLB
42c0: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ACK | result cod
42d0: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  es]..*/.#define 
42e0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
42f0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4300: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4310: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4320: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
4330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4340: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4350: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
4360: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
4370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4380: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4390: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
43a0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
43b0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
43c0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
43d0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
43e0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
43f0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4400: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4410: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4420: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4430: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4450: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4460: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4470: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
44a0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
44b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
44c0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
44e0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
44f0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4510: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4520: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4530: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4540: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4560: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4570: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4580: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4590: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
45a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
45b0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
45c0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
45d0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
45e0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
45f0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4600: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4610: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4620: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4650: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4660: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4670: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
46a0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
46b0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
46c0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
46f0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4700: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4710: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4730: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4740: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4750: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4770: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4780: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4790: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
47a0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
47b0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
47c0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
47d0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
47e0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
47f0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4800: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4810: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4830: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4840: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4850: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4860: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4870: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4880: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4890: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48b0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
48c0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
48d0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
48f0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4900: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4910: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4920: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4940: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4950: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4960: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4970: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4980: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4990: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
49a0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
49b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
49c0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
49d0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
49e0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
49f0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a10: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a20: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4a30: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4a40: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4a60: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4a70: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4a80: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4a90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4aa0: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4ab0: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4ac0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4ad0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4ae0: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4af0: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b00: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b10: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b30: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4b40: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4b50: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4b60: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4b70: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4b80: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4b90: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4ba0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4bb0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4bc0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
4bd0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4be0: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4bf0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4c00: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4c10: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4c20: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4c30: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4c40: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4c50: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4c60: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4c70: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
4c80: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4c90: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4ca0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4cb0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4cc0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4cd0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4ce0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4cf0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4d00: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4d10: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4d20: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4d30: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4d40: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4d50: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4d60: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4d70: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4d80: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4d90: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4da0: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4db0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4dc0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4dd0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4de0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4df0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4e00: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4e10: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4e20: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4e30: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4e40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4e50: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4e60: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e70: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4e80: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
4e90: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
4ea0: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
4eb0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4ec0: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
4ed0: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4ee0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4ef0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f00: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4f10: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4f20: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4f30: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4f40: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4f50: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
4f60: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
4f70: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
4f80: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
4f90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
4fa0: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
4fb0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
4fc0: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
4fd0: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
4fe0: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
4ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5000: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
5010: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5020: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
5030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5040: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
5050: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5060: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
5070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5080: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
5090: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50a0: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
50b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50c0: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
50d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50e0: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
50f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5100: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
5110: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5120: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5180: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
5190: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51a0: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
51b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
51c0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
51d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51e0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
51f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
5200: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5210: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5220: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5230: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5240: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
5250: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5260: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
5270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
5280: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
5290: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52a0: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
52c0: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52e0: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
52f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
5300: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
5310: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5320: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
5330: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
5340: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
5350: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5360: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
5370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
5380: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53a0: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
53b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
53c0: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53e0: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
5400: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5420: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5440: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
5450: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5460: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
5470: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5480: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
5490: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54a0: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
54b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
54c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
54d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54e0: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
54f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5500: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
5510: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5520: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
5530: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
5540: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5560: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
5570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5580: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28  ETE_NOENT      (
5590: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55a0: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  23<<8)).#define 
55b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41  SQLITE_IOERR_MMA
55c0: 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  P              (
55d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55e0: 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  24<<8)).#define 
55f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54  SQLITE_IOERR_GET
5600: 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 28  TEMPPATH       (
5610: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5620: 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  25<<8)).#define 
5630: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e  SQLITE_IOERR_CON
5640: 56 50 41 54 48 20 20 20 20 20 20 20 20 20 20 28  VPATH          (
5650: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5660: 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  26<<8)).#define 
5670: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
5680: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
5690: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
56a0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
56b0: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
56c0: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
56d0: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
56e0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
56f0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e  e SQLITE_BUSY_SN
5700: 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20  APSHOT          
5710: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5720: 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69  |  (2<<8)).#defi
5730: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5740: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5750: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5760: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
5770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5780: 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20  OPEN_ISDIR      
5790: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
57a0: 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OPEN | (2<<8)).#
57b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
57c0: 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20  NTOPEN_FULLPATH 
57d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
57e0: 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29  NTOPEN | (3<<8))
57f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5800: 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54  CANTOPEN_CONVPAT
5810: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
5820: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38  CANTOPEN | (4<<8
5830: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5840: 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20  E_CORRUPT_VTAB  
5850: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5860: 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c  E_CORRUPT | (1<<
5870: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5880: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f  TE_READONLY_RECO
5890: 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49  VERY       (SQLI
58a0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31  TE_READONLY | (1
58b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
58c0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41  LITE_READONLY_CA
58d0: 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51  NTLOCK       (SQ
58e0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
58f0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5900: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5910: 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28  ROLLBACK       (
5920: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5930: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5940: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
5950: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
5960: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
5970: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5980: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5990: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
59a0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59b0: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
59c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
59d0: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
59e0: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
59f0: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
5a00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a10: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
5a20: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
5a30: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
5a40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a50: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5a60: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
5a70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5a80: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5a90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5aa0: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
5ab0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5ac0: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
5ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5ae0: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
5af0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5b00: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
5b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b20: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
5b30: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
5b40: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
5b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b60: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
5b70: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
5b80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5b90: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
5ba0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5bb0: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
5bc0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5bd0: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  NT | (9<<8)).#de
5be0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5bf0: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20  TRAINT_ROWID    
5c00: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5c10: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29  TRAINT |(10<<8))
5c20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c30: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57  NOTICE_RECOVER_W
5c40: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  AL      (SQLITE_
5c50: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29  NOTICE | (1<<8))
5c60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c70: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52  NOTICE_RECOVER_R
5c80: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f  OLLBACK (SQLITE_
5c90: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29  NOTICE | (2<<8))
5ca0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5cb0: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45  WARNING_AUTOINDE
5cc0: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  X       (SQLITE_
5cd0: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29  WARNING | (1<<8)
5ce0: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5cf0: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5d00: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5d10: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5d20: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5d30: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5d40: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5d50: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5d60: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5d70: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5d80: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5d90: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5da0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
5db0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
5dc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5dd0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5de0: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5df0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5e00: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5e20: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5e30: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5e40: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5e50: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5e60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5e70: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
5e80: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
5e90: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5ea0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5eb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5ec0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
5ed0: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
5ee0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5ef0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f00: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
5f10: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
5f20: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5f30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f40: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
5f50: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
5f60: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5f70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f80: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
5f90: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
5fa0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5fb0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5fc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5fd0: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
5fe0: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
5ff0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6000: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6020: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
6030: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
6040: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6060: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
6070: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
6080: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60a0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
60b0: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
60c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
60d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60e0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
60f0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
6100: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6120: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
6130: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
6140: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6160: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
6170: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
6180: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6190: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61a0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
61b0: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
61c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61e0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
61f0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
6200: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6210: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6220: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6230: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
6240: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
6250: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6260: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6280: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
6290: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
62a0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
62b0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
62c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62d0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
62e0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
62f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6300: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6310: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6320: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
6330: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
6340: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
6350: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
6360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6370: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
6380: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6390: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
63a0: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
63b0: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
63c0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
63d0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
63e0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
63f0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
6400: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
6410: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
6420: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
6430: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
6440: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
6450: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
6460: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
6470: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
6480: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
6490: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
64a0: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
64b0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
64c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
64d0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
64e0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
64f0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
6500: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6510: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6520: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
6530: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
6540: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
6550: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
6560: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
6570: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
6580: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
6590: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
65a0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
65b0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
65c0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
65d0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
65e0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
65f0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
6600: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
6610: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
6620: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
6630: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
6640: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
6650: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
6660: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
6670: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6680: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
6690: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
66a0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
66b0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
66c0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
66d0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
66e0: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68  to xWrite().  Th
66f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
6700: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
6710: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  TE property mean
6720: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20  s that.** after 
6730: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67  reboot following
6740: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65   a crash or powe
6750: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79  r loss, the only
6760: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66   bytes in a.** f
6770: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72  ile that were wr
6780: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70  itten at the app
6790: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d  lication level m
67a0: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65  ight have change
67b0: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64  d.** and that ad
67c0: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76  jacent bytes, ev
67d0: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20  en bytes within 
67e0: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20  the same sector 
67f0: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  are.** guarantee
6800: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65  d to be unchange
6810: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
6820: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6830: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
6840: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
6850: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6860: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
6870: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6880: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
6890: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
68a0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
68b0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
68c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
68d0: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
68e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
68f0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
6900: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
6910: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6920: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
6930: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6940: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20  OMIC8K          
6950: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
6960: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6970: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
6980: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6990: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
69a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
69b0: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20  IC32K           
69c0: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
69d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
69e0: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
69f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6a00: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
6a10: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6a20: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20  PPEND           
6a30: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
6a40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a50: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
6a60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34          0x000004
6a70: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6a80: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
6a90: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30  BLE_WHEN_OPEN  0
6aa0: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e  x00000800.#defin
6ab0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
6ac0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
6ad0: 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30  TE    0x00001000
6ae0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6af0: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c  : File Locking L
6b00: 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  evels.**.** SQLi
6b10: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74  te uses one of t
6b20: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6b30: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6b40: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
6b50: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20   calls it makes 
6b60: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61  to the xLock() a
6b70: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74  nd xUnlock() met
6b80: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  hods.** of an [s
6b90: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6ba0: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
6bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6bc0: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20  K_NONE          
6bd0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6be0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20  _LOCK_SHARED    
6bf0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
6c00: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
6c10: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  ED      2.#defin
6c20: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45  e SQLITE_LOCK_PE
6c30: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64  NDING       3.#d
6c40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6c50: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  K_EXCLUSIVE     
6c60: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
6c70: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69  F: Synchronizati
6c80: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a  on Type Flags.**
6c90: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
6ca0: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
6cb0: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
6cc0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
6cd0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
6ce0: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
6cf0: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
6d00: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6d10: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
6d20: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
6d30: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
6d40: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
6d50: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
6d60: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
6d70: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
6d80: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
6d90: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
6da0: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
6db0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
6dc0: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
6dd0: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72  ed. If the lower
6de0: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68   four bits of th
6df0: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20  e flag.** equal 
6e00: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6e10: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  AL, that means t
6e20: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
6e30: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
6e40: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  ** If the lower 
6e50: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20  four bits equal 
6e60: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6e70: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
6e80: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
6e90: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
6ea0: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
6eb0: 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20  )..**.** Do not 
6ec0: 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49  confuse the SQLI
6ed0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
6ee0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
6ef0: 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74  ULL flags.** wit
6f00: 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79  h the [PRAGMA sy
6f10: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41  nchronous]=NORMA
6f20: 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79  L and [PRAGMA sy
6f30: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a  nchronous]=FULL.
6f40: 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68  ** settings.  Th
6f50: 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70  e [synchronous p
6f60: 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65  ragma] determine
6f70: 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  s when calls to 
6f80: 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53  the.** xSync VFS
6f90: 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e   method occur an
6fa0: 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72  d applies unifor
6fb0: 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70  mly across all p
6fc0: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65  latforms..** The
6fd0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
6fe0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
6ff0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64  YNC_FULL flags d
7000: 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20  etermine how.** 
7010: 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67  energetic or rig
7020: 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75  orous or forcefu
7030: 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61  l the sync opera
7040: 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a  tions are and.**
7050: 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66   only make a dif
7060: 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f  ference on Mac O
7070: 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75  SX for the defau
7080: 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a  lt SQLite code..
7090: 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20  ** (Third-party 
70a0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
70b0: 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d  ons might also m
70c0: 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
70d0: 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53  ion.** between S
70e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
70f0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
7100: 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e  C_FULL, but amon
7110: 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69  g the.** operati
7120: 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76  ng systems nativ
7130: 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79  ely supported by
7140: 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61   SQLite, only Ma
7150: 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61  c OSX.** cares a
7160: 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65  bout the differe
7170: 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65  nce.).*/.#define
7180: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7190: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
71a0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
71b0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
71c0: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
71d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
71e0: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
71f0: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
7200: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
7210: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
7220: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  andle.**.** An [
7230: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7240: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
7250: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
7260: 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
7270: 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66  _vfs | OS interf
7280: 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64  ace layer].  Ind
7290: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72  ividual OS inter
72a0: 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  face.** implemen
72b0: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
72c0: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
72d0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
72e0: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
72f0: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
7300: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
7310: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
7320: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
7330: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
7340: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7350: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
7360: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
7370: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
7380: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
7390: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
73a0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
73b0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
73c0: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
73d0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
73e0: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
73f0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
7400: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
7410: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
7420: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
7430: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
7440: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7450: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
7460: 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
7470: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
7480: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
7490: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
74a0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
74b0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
74c0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
74d0: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
74e0: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
74f0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
7500: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
7510: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
7520: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
7530: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
7540: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
7550: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
7560: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
7570: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
7580: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
7590: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
75a0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
75b0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
75c0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ct..**.** If the
75d0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
75e0: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73  pen] method sets
75f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
7600: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
7610: 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d  nt .** to a non-
7620: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
7630: 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  en the sqlite3_i
7640: 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65  o_methods.xClose
7650: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62   method.** may b
7660: 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69  e invoked even i
7670: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
7680: 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74  fs.xOpen] report
7690: 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65  ed that it faile
76a0: 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20  d.  The.** only 
76b0: 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61  way to prevent a
76c0: 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20   call to xClose 
76d0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
76e0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  ed [sqlite3_vfs.
76f0: 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72  xOpen].** is for
7700: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7710: 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20  s.xOpen] to set 
7720: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
7730: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
7740: 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  t.** to NULL..**
7750: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
7760: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
7770: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
7780: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7790: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
77a0: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
77b0: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
77c0: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
77d0: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nc()..** The sec
77e0: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20  ond choice is a 
77f0: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
7800: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53  ullsync.  The [S
7810: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7820: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79  NLY].** flag may
7830: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69   be ORed in to i
7840: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c  ndicate that onl
7850: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68  y the data of th
7860: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f  e file.** and no
7870: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64  t its inode need
7880: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a  s to be synced..
7890: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65  **.** The intege
78a0: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63  r values to xLoc
78b0: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
78c0: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  ) are one of.** 
78d0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
78e0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
78f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7900: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
7910: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7920: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a  OCK_RESERVED],.*
7930: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7940: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
7950: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7960: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
7970: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c  ..** </ul>.** xL
7980: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20  ock() increases 
7990: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63  the lock. xUnloc
79a0: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68  k() decreases th
79b0: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78  e lock..** The x
79c0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
79d0: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b  k() method check
79e0: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61  s whether any da
79f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7a00: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20  n,.** either in 
7a10: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20  this process or 
7a20: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
7a30: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
7a40: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a  g a RESERVED,.**
7a50: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43   PENDING, or EXC
7a60: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74  LUSIVE lock on t
7a70: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74  he file.  It ret
7a80: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20  urns true.** if 
7a90: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73  such a lock exis
7aa0: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68  ts and false oth
7ab0: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erwise..**.** Th
7ac0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
7ad0: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
7ae0: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
7af0: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
7b00: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
7b10: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
7b20: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
7b30: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
7b40: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
7b50: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
7b60: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
7b70: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
7b80: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e  ment is an.** in
7b90: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54  teger opcode.  T
7ba0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
7bb0: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70  t is a generic p
7bc0: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20  ointer intended 
7bd0: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  to.** point to a
7be0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
7bf0: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75  may contain argu
7c00: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69  ments or space i
7c10: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72  n which to.** wr
7c20: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ite return value
7c30: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73  s.  Potential us
7c40: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74  es for xFileCont
7c50: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a  rol() might be.*
7c60: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65  * functions to e
7c70: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c  nable blocking l
7c80: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75  ocks with timeou
7c90: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ts, to change th
7ca0: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72  e.** locking str
7cb0: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70  ategy (for examp
7cc0: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69  le to use dot-fi
7cd0: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e  le locks), to in
7ce0: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74  quire.** about t
7cf0: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c  he status of a l
7d00: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b  ock, or to break
7d10: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54   stale locks.  T
7d20: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72  he SQLite.** cor
7d30: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f  e reserves all o
7d40: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
7d50: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
7d60: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49   use..** A [SQLI
7d70: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
7d80: 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63  TE | list of opc
7d90: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20  odes] less than 
7da0: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65  100 is available
7db0: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
7dc0: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20  s that define a 
7dd0: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74  custom xFileCont
7de0: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  rol method shoul
7df0: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a  d use opcodes.**
7e00: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30   greater than 10
7e10: 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c  0 to avoid confl
7e20: 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65  icts.  VFS imple
7e30: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
7e40: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
7e50: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f  ITE_NOTFOUND] fo
7e60: 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f  r file control o
7e70: 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79  pcodes that they
7e80: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67   do not.** recog
7e90: 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nize..**.** The 
7ea0: 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65  xSectorSize() me
7eb0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65  thod returns the
7ec0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20   sector size of 
7ed0: 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  the.** device th
7ee0: 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65  at underlies the
7ef0: 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74   file.  The sect
7f00: 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a  or size is the.*
7f10: 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20  * minimum write 
7f20: 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66  that can be perf
7f30: 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69  ormed without di
7f40: 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65  sturbing.** othe
7f50: 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  r bytes in the f
7f60: 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63  ile.  The xDevic
7f70: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7f80: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
7f90: 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f  urns a bit vecto
7fa0: 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68  r describing beh
7fb0: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a  aviors of the.**
7fc0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69   underlying devi
7fd0: 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce:.**.** <ul>.*
7fe0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7ff0: 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20  OCAP_ATOMIC].** 
8000: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8010: 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a  AP_ATOMIC512].**
8020: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8030: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a  CAP_ATOMIC1K].**
8040: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8050: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a  CAP_ATOMIC2K].**
8060: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8070: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a  CAP_ATOMIC4K].**
8080: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8090: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a  CAP_ATOMIC8K].**
80a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
80b0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a  CAP_ATOMIC16K].*
80c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
80d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a  OCAP_ATOMIC32K].
80e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
80f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d  IOCAP_ATOMIC64K]
8100: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8110: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
8120: 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ND].** <li> [SQL
8130: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
8140: 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  TIAL].** </ul>.*
8150: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
8160: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
8170: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8180: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
8190: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
81a0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
81b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
81c0: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
81d0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
81e0: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
81f0: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
8200: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
8210: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
8220: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
8230: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
8240: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
8250: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
8260: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
8270: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
8280: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
8290: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
82a0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
82b0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
82c0: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
82d0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
82e0: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
82f0: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
8300: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
8310: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8320: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
8330: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
8340: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
8350: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
8360: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
8370: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
8380: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
8390: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
83a0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
83b0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
83c0: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
83d0: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
83e0: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
83f0: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
8400: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
8410: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
8420: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8430: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
8440: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
8450: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
8460: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8470: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
8480: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
8490: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
84a0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
84b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
84c0: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
84d0: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
84e0: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
84f0: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
8500: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
8510: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
8520: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8530: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
8540: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
8550: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8560: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8570: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
8580: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
8590: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
85a0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
85b0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
85c0: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
85d0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
85e0: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
85f0: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
8600: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8610: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
8620: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
8630: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8640: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
8650: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
8660: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8670: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8680: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
8690: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
86a0: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
86b0: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
86c0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
86d0: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
86e0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
86f0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8700: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
8710: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
8720: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
8730: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
8740: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8750: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
8760: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
8770: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8780: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
8790: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
87a0: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
87b0: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
87c0: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
87d0: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
87e0: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
87f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8800: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
8810: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8820: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
8830: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
8840: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8850: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
8860: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
8870: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
8880: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8890: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
88a0: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65  2 */.  int (*xFe
88b0: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
88c0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
88d0: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d  4 iOfst, int iAm
88e0: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20  t, void **pp);. 
88f0: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29   int (*xUnfetch)
8900: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8910: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8920: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20  fst, void *p);. 
8930: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8940: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8950: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f  version 3 */.  /
8960: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
8970: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
8980: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
8990: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
89a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
89b0: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
89c0: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  l Opcodes.**.** 
89d0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
89e0: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
89f0: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
8a00: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
8a10: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
8a20: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
8a30: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
8a40: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
8a50: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
8a60: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
8a70: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8a80: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
8a90: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
8aa0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
8ab0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
8ac0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
8ad0: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
8ae0: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
8af0: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
8b00: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
8b10: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
8b20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
8b30: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
8b40: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
8b50: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
8b60: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
8b70: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
8b80: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
8b90: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
8ba0: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
8bb0: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
8bc0: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
8bd0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
8be0: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
8bf0: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
8c00: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
8c10: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
8c20: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8c30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
8c40: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68  IZE_HINT]].** Th
8c50: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8c60: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
8c70: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
8c80: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
8c90: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
8ca0: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
8cb0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
8cc0: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
8cd0: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
8ce0: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
8cf0: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
8d00: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
8d10: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
8d20: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
8d30: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
8d40: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
8d50: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
8d60: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
8d70: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
8d80: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
8d90: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
8da0: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
8db0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
8dc0: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
8dd0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
8de0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
8df0: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
8e00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
8e10: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20  NK_SIZE] opcode 
8e20: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65  is used to reque
8e30: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a  st that the VFS.
8e40: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74  ** extends and t
8e50: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74  runcates the dat
8e60: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68  abase file in ch
8e70: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73  unks of a size s
8e80: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
8e90: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75  he user. The fou
8ea0: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
8eb0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8ec0: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20  ntrol()] should 
8ed0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
8ee0: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e  integer (type in
8ef0: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  t) containing th
8f00: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65  e new chunk-size
8f10: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74   to use.** for t
8f20: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74  he nominated dat
8f30: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e  abase. Allocatin
8f40: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  g database file 
8f50: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a  space in large.*
8f60: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d  * chunks (say 1M
8f70: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61  B at a time), ma
8f80: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79  y reduce file-sy
8f90: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69  stem fragmentati
8fa0: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76  on and.** improv
8fb0: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e  e performance on
8fc0: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a   some systems..*
8fd0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8fe0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
8ff0: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
9000: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
9010: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
9020: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
9030: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
9040: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
9050: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
9060: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
9070: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
9080: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
9090: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
90a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
90b0: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
90c0: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
90d0: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
90e0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
90f0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
9100: 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68  MITTED]].** ^(Th
9110: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9120: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70  SYNC_OMITTED] op
9130: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
9140: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a  d internally by.
9150: 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65  ** SQLite and se
9160: 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20  nt to all VFSes 
9170: 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61  in place of a ca
9180: 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20  ll to the xSync 
9190: 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74  method.** when t
91a0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
91b0: 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47  ection has [PRAG
91c0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20  MA synchronous] 
91d0: 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a  set to OFF.)^.**
91e0: 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65   Some specialize
91f0: 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69  d VFSes need thi
9200: 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65  s signal in orde
9210: 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72  r to operate cor
9220: 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b  rectly.** when [
9230: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
9240: 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63  us | PRAGMA sync
9250: 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20  hronous=OFF] is 
9260: 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a  set, but most .*
9270: 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e  * VFSes do not n
9280: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
9290: 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  and should silen
92a0: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
92b0: 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69  opcode..** Appli
92c0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
92d0: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
92e0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
92f0: 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70   with this.** op
9300: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
9310: 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65   may disrupt the
9320: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
9330: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
9340: 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72  Ses.** that do r
9350: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9360: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9370: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9380: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9390: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
93a0: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
93b0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
93c0: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
93d0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
93e0: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
93f0: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
9400: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
9410: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
9420: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
9430: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
9440: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
9450: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
9460: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
9470: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
9480: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
9490: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
94a0: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
94b0: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
94c0: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
94d0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
94e0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
94f0: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
9500: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
9510: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
9520: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
9530: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
9540: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
9550: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
9560: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
9570: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
9580: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
9590: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
95a0: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
95b0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
95c0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
95d0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
95e0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
95f0: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
9600: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
9610: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
9620: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
9630: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
9640: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9650: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
9660: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
9670: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9680: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
9690: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
96a0: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
96b0: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
96c0: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
96d0: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
96e0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
96f0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9700: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9710: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9720: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
9730: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
9740: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
9750: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
9760: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
9770: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
9780: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
9790: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
97a0: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
97b0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
97c0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
97d0: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
97e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
97f0: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
9800: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9810: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9820: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
9830: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
9840: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
9850: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
9860: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
9870: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
9880: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
9890: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
98a0: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
98b0: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
98c0: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
98d0: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
98e0: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
98f0: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
9900: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
9910: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
9920: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
9930: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
9940: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
9950: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
9960: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
9970: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
9980: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
9990: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
99a0: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
99b0: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
99c0: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
99d0: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
99e0: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
99f0: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
9a00: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
9a10: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
9a20: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
9a30: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
9a40: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
9a50: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
9a60: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9a70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9a80: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
9a90: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
9aa0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
9ab0: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
9ac0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
9ad0: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
9ae0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
9af0: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
9b00: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
9b10: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
9b20: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
9b30: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
9b40: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
9b50: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
9b60: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
9b70: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9b80: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
9b90: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
9ba0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
9bb0: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
9bc0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
9bd0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9be0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9bf0: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
9c00: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
9c10: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
9c20: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
9c30: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
9c40: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
9c50: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
9c60: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
9c70: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
9c80: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
9c90: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
9ca0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
9cb0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
9cc0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
9cd0: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
9ce0: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
9cf0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
9d00: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
9d10: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
9d20: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
9d30: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
9d40: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
9d50: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
9d60: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
9d70: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
9d80: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
9d90: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
9da0: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
9db0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9dc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
9dd0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
9de0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
9df0: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
9e00: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
9e10: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
9e20: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
9e30: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
9e40: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
9e50: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
9e60: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
9e70: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
9e80: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
9e90: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
9ea0: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
9eb0: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
9ec0: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
9ed0: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
9ee0: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
9ef0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9f00: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
9f10: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9f20: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
9f30: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
9f40: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
9f50: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
9f60: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
9f70: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
9f80: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
9f90: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
9fa0: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
9fb0: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
9fc0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
9fd0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
9fe0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
9ff0: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
a000: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
a010: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a020: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
a030: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a040: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
a050: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
a060: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
a070: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
a080: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
a090: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
a0a0: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
a0b0: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
a0c0: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
a0d0: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
a0e0: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
a0f0: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
a100: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
a110: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
a120: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
a130: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
a140: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
a150: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
a160: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
a170: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
a180: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
a190: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
a1a0: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
a1b0: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
a1c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
a1d0: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e  RAGMA]].** ^When
a1e0: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20  ever a [PRAGMA] 
a1f0: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72  statement is par
a200: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f  sed, an [SQLITE_
a210: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a  FCNTL_PRAGMA] .*
a220: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  * file control i
a230: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70  s sent to the op
a240: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  en [sqlite3_file
a250: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70  ] object corresp
a260: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  onding.** to the
a270: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
a280: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67  o which the prag
a290: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66  ma statement ref
a2a0: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65  ers. ^The argume
a2b0: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51  nt.** to the [SQ
a2c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a2d0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a2e0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a  is an array of.*
a2f0: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  * pointers to st
a300: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69  rings (char**) i
a310: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f  n which the seco
a320: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68  nd element of th
a330: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68  e array.** is th
a340: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72  e name of the pr
a350: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69  agma and the thi
a360: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68  rd element is th
a370: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  e argument to th
a380: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e  e.** pragma or N
a390: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d  ULL if the pragm
a3a0: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e  a has no argumen
a3b0: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  t.  ^The handler
a3c0: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49   for an.** [SQLI
a3d0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a3e0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61   file control ca
a3f0: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b  n optionally mak
a400: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d  e the first elem
a410: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68  ent.** of the ch
a420: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f  ar** argument po
a430: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
a440: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
a450: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
a460: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69  ].** or the equi
a470: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20  valent and that 
a480: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f  string will beco
a490: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  me the result of
a4a0: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a   the pragma or.*
a4b0: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
a4c0: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d  age if the pragm
a4d0: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65  a fails. ^If the
a4e0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
a4f0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a500: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
a510: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
a520: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
a530: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
a540: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
a550: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
a560: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
a570: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
a580: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
a590: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61  OK], then the pa
a5a0: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61  rser assumes tha
a5b0: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73  t the.** VFS has
a5c0: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41   handled the PRA
a5d0: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74  GMA itself and t
a5e0: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61  he parser genera
a5f0: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70  tes a no-op.** p
a600: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
a610: 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  t.  ^If the [SQL
a620: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a630: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
a640: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
a650: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
a660: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
a670: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
a680: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
a690: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
a6a0: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
a6b0: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
a6c0: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
a6d0: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
a6e0: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
a6f0: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
a700: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
a710: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a720: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
a730: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
a740: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
a750: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
a760: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
a770: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
a780: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
a790: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
a7a0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
a7b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a7c0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
a7d0: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
a7e0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
a7f0: 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63  NDLER].** file-c
a800: 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e  ontrol may be in
a810: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
a820: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
a830: 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73  file handle.** s
a840: 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20  hortly after it 
a850: 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64  is opened in ord
a860: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20  er to provide a 
a870: 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20  custom VFS with 
a880: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65  access.** to the
a890: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73   connections bus
a8a0: 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
a8b0: 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74  ck. The argument
a8c0: 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69   is of type (voi
a8d0: 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72  d **).** - an ar
a8e0: 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64  ray of two (void
a8f0: 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20   *) values. The 
a900: 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61  first (void *) a
a910: 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a  ctually points.*
a920: 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  * to a function 
a930: 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29  of type (int (*)
a940: 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72  (void *)). In or
a950: 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68  der to invoke th
a960: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
a970: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74   busy-handler, t
a980: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
a990: 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  uld be invoked w
a9a0: 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28  ith the second (
a9b0: 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68  void *) in.** th
a9c0: 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f  e array as the o
a9d0: 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  nly argument. If
a9e0: 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d   it returns non-
a9f0: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f  zero, then the o
aa00: 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  peration.** shou
aa10: 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49  ld be retried. I
aa20: 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72  f it returns zer
aa30: 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46  o, the custom VF
aa40: 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e  S should abandon
aa50: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
aa60: 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  operation..**.**
aa70: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
aa80: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
aa90: 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69  ]].** ^Applicati
aaa0: 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68  on can invoke th
aab0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aac0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69  TEMPFILENAME] fi
aad0: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f  le-control.** to
aae0: 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e   have SQLite gen
aaf0: 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f  erate a.** tempo
ab00: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73  rary filename us
ab10: 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
ab20: 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66  orithm that is f
ab30: 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72  ollowed to gener
ab40: 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
ab50: 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54   filenames for T
ab60: 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f  EMP tables and o
ab70: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73  ther internal us
ab80: 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75  es.  The.** argu
ab90: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61  ment should be a
aba0: 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69   char** which wi
abb0: 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74  ll be filled wit
abc0: 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  h the filename.*
abd0: 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  * written into m
abe0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
abf0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
ac00: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c  loc()].  The cal
ac10: 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e  ler should.** in
ac20: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
ac30: 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73  ee()] on the res
ac40: 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d  ult to avoid a m
ac50: 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a  emory leak..**.*
ac60: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ac70: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  CNTL_MMAP_SIZE]]
ac80: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
ac90: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
aca0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
acb0: 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f   used to query o
acc0: 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78  r set the.** max
acd0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
ace0: 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ytes that will b
acf0: 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72  e used for memor
ad00: 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a  y-mapped I/O..**
ad10: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
ad20: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
ad30: 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71  value of type sq
ad40: 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74  lite3_int64 that
ad50: 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f  .** is an adviso
ad60: 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ry maximum numbe
ad70: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
ad80: 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79  e file to memory
ad90: 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f   map.  The.** po
ada0: 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69  inter is overwri
adb0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c  tten with the ol
adc0: 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69  d value.  The li
add0: 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  mit is not chang
ade0: 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c  ed if.** the val
adf0: 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f  ue originally po
ae00: 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61  inted to is nega
ae10: 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  tive, and so the
ae20: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a   current limit .
ae30: 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  ** can be querie
ae40: 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20  d by passing in 
ae50: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
ae60: 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20  egative number. 
ae70: 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f   This.** file-co
ae80: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e  ntrol is used in
ae90: 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c  ternally to impl
aea0: 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d  ement [PRAGMA mm
aeb0: 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20  ap_size]..**.** 
aec0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
aed0: 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68  TL_TRACE]].** Th
aee0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aef0: 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74  TRACE] file cont
af00: 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76  rol provides adv
af10: 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f  isory informatio
af20: 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20  n.** to the VFS 
af30: 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68  about what the h
af40: 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20  igher layers of 
af50: 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b  the SQLite stack
af60: 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54   are doing..** T
af70: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
af80: 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65   is used by some
af90: 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72   VFS activity tr
afa0: 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a  acing [shims]..*
afb0: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
afc0: 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
afd0: 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67  ted string.  Hig
afe0: 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68  her layers in th
aff0: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63  e.** SQLite stac
b000: 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69  k may generate i
b010: 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73  nstances of this
b020: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66   file control if
b030: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
b040: 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  USE_FCNTL_TRACE]
b050: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
b060: 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
b070: 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .**.** </ul>.*/.
b080: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b090: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
b0a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
b0b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45  define SQLITE_GE
b0c0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
b0d0: 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
b0e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54  efine SQLITE_SET
b0f0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
b100: 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
b110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
b120: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
b130: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
b140: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b150: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
b160: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
b170: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b180: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
b190: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
b1a0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
b1b0: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
b1c0: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
b1d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
b1e0: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
b1f0: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
b200: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b210: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
b220: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
b230: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
b240: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
b250: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
b260: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
b270: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
b280: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
b290: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
b2a0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
b2b0: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
b2c0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
b2d0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
b2e0: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
b2f0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
b300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
b310: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
b320: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
b330: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
b340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b350: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
b360: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
b370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b380: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
b390: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
b3a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b3b0: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
b3c0: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 0a 2f             19../
b3d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
b3e0: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
b3f0: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
b400: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
b410: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
b420: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
b430: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
b440: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
b450: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
b460: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
b470: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
b480: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
b490: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
b4a0: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
b4b0: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
b4c0: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
b4d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
b4e0: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
b4f0: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
b500: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
b510: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
b520: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
b530: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
b540: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
b550: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
b560: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
b570: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
b580: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
b590: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
b5a0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
b5b0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
b5c0: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
b5d0: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
b5e0: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
b5f0: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
b600: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
b610: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
b620: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
b630: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
b640: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
b650: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
b660: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
b670: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
b680: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
b690: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
b6a0: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
b6b0: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
b6c0: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
b6d0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
b6e0: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
b6f0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
b700: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
b710: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
b720: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
b730: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
b740: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
b750: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
b760: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
b770: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
b780: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
b790: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
b7a0: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
b7b0: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
b7c0: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
b7d0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
b7e0: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
b7f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
b800: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
b810: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
b820: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
b830: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
b840: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
b850: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
b860: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
b870: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
b880: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
b890: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
b8a0: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
b8b0: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
b8c0: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
b8d0: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
b8e0: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
b8f0: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
b900: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
b910: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
b920: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
b930: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
b940: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
b950: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
b960: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
b970: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
b980: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
b990: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
b9a0: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
b9b0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
b9c0: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
b9d0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
b9e0: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
b9f0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
ba00: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
ba10: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
ba20: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
ba30: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
ba40: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
ba50: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
ba60: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
ba70: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
ba80: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
ba90: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
baa0: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
bab0: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
bac0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
bad0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
bae0: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
baf0: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
bb00: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
bb10: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
bb20: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
bb30: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
bb40: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
bb50: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
bb60: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
bb70: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
bb80: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
bb90: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
bba0: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
bbb0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
bbc0: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
bbd0: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
bbe0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
bbf0: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
bc00: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
bc10: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
bc20: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
bc30: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
bc40: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
bc50: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
bc60: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
bc70: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
bc80: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
bc90: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
bca0: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
bcb0: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
bcc0: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
bcd0: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
bce0: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
bcf0: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
bd00: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
bd10: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
bd20: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
bd30: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
bd40: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
bd50: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
bd60: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
bd70: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
bd80: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
bd90: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
bda0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
bdb0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
bdc0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
bdd0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
bde0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
bdf0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
be00: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
be10: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
be20: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
be30: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
be40: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
be50: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
be60: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
be70: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
be80: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
be90: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
bea0: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
beb0: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
bec0: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
bed0: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
bee0: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
bef0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
bf00: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
bf10: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
bf20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
bf30: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
bf40: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
bf50: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
bf60: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
bf70: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
bf80: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
bf90: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
bfa0: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
bfb0: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
bfc0: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
bfd0: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
bfe0: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
bff0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
c000: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
c010: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
c020: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
c030: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
c040: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
c050: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
c060: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
c070: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
c080: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
c090: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
c0a0: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
c0b0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
c0c0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
c0d0: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
c0e0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
c0f0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
c100: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
c110: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
c120: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
c130: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c140: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
c150: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
c160: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
c170: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c180: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
c190: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
c1a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
c1b0: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
c1c0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c1d0: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
c1e0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c1f0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
c200: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c210: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
c220: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
c230: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
c240: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
c250: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
c260: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
c270: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
c280: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
c290: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
c2a0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
c2b0: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
c2c0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
c2d0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
c2e0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
c2f0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
c300: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
c310: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
c320: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
c330: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
c340: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
c350: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
c360: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
c370: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
c380: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
c390: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
c3a0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
c3b0: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
c3c0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
c3d0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
c3e0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
c3f0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
c400: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
c410: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
c420: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
c430: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
c440: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
c450: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
c460: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
c470: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
c480: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
c490: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
c4a0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
c4b0: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
c4c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
c4d0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
c4e0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
c4f0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
c500: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
c510: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
c520: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
c530: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
c540: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
c550: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
c560: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
c570: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
c580: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
c590: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
c5a0: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
c5b0: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
c5c0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
c5d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
c5e0: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
c5f0: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
c600: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
c610: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
c620: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
c630: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
c640: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
c650: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
c660: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
c670: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
c680: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
c690: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
c6a0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
c6b0: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
c6c0: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
c6d0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
c6e0: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
c6f0: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
c700: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
c710: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
c720: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
c730: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
c740: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
c750: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
c760: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
c770: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
c780: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
c790: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
c7a0: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
c7b0: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
c7c0: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
c7d0: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
c7e0: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
c7f0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
c800: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
c810: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
c820: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
c830: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
c840: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
c850: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
c860: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
c870: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
c880: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
c890: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
c8a0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
c8b0: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
c8c0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
c8d0: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
c8e0: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
c8f0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
c900: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
c910: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
c920: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
c930: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
c940: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
c950: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
c960: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
c970: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
c980: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
c990: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
c9a0: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
c9b0: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
c9c0: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
c9d0: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
c9e0: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
c9f0: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
ca00: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
ca10: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
ca20: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
ca30: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
ca40: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
ca50: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
ca60: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
ca70: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
ca80: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
ca90: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
caa0: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
cab0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
cac0: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
cad0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
cae0: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
caf0: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
cb00: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
cb10: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
cb20: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
cb30: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
cb40: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
cb50: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
cb60: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
cb70: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
cb80: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
cb90: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
cba0: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
cbb0: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
cbc0: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
cbd0: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
cbe0: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
cbf0: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
cc00: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
cc10: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
cc20: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
cc30: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
cc40: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
cc50: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
cc60: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
cc70: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
cc80: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
cc90: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
cca0: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
ccb0: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
ccc0: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
ccd0: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
cce0: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
ccf0: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
cd00: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
cd10: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
cd20: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
cd30: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
cd40: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
cd50: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
cd60: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
cd70: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
cd80: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
cd90: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
cda0: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
cdb0: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
cdc0: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
cdd0: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
cde0: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
cdf0: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
ce00: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
ce10: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
ce20: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
ce30: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
ce40: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
ce50: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
ce60: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
ce70: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
ce80: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
ce90: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
cea0: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
ceb0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
cec0: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
ced0: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
cee0: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
cef0: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
cf00: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
cf10: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
cf20: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
cf30: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
cf40: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
cf50: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
cf60: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
cf70: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
cf80: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
cf90: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
cfa0: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
cfb0: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
cfc0: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
cfd0: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
cfe0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
cff0: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
d000: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
d010: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
d020: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
d030: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
d040: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
d050: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
d060: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
d070: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
d080: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
d090: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
d0a0: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
d0b0: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
d0c0: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
d0d0: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
d0e0: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
d0f0: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
d100: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
d110: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
d120: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
d130: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
d140: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
d150: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
d160: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
d170: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
d180: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
d190: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
d1a0: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
d1b0: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
d1c0: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
d1d0: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
d1e0: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
d1f0: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
d200: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
d210: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
d220: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
d230: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
d240: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
d250: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
d260: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
d270: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
d280: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
d290: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
d2a0: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
d2b0: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
d2c0: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
d2d0: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
d2e0: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
d2f0: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
d300: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
d310: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
d320: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
d330: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
d340: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
d350: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
d360: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
d370: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
d380: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
d390: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
d3a0: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
d3b0: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
d3c0: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
d3d0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
d3e0: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
d3f0: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
d400: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
d410: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
d420: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
d430: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
d440: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
d450: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
d460: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
d470: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
d480: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
d490: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
d4a0: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
d4b0: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
d4c0: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
d4d0: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
d4e0: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
d4f0: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
d500: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
d510: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
d520: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
d530: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
d540: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
d550: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
d560: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
d570: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
d580: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
d590: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
d5a0: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
d5b0: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
d5c0: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
d5d0: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
d5e0: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
d5f0: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
d600: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
d610: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
d620: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
d630: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
d640: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
d650: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
d660: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d670: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
d680: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
d690: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
d6a0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d6b0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
d6c0: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
d6d0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
d6e0: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
d6f0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
d700: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d710: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
d720: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
d730: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
d740: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
d750: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
d760: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
d770: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
d780: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
d790: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
d7a0: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
d7b0: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
d7c0: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
d7d0: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
d7e0: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
d7f0: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
d800: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
d810: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
d820: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
d830: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
d840: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
d850: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
d860: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
d870: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
d880: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
d890: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
d8a0: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
d8b0: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
d8c0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
d8d0: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
d8e0: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
d8f0: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
d900: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
d910: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
d920: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
d930: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
d940: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
d950: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
d960: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
d970: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
d980: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
d990: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
d9a0: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
d9b0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
d9c0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
d9d0: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
d9e0: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
d9f0: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
da00: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
da10: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
da20: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
da30: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
da40: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
da50: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
da60: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
da70: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
da80: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
da90: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
daa0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
dab0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
dac0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
dad0: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
dae0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
daf0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
db00: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
db10: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
db20: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
db30: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
db40: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
db50: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
db60: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
db70: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
db80: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
db90: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
dba0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
dbb0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
dbc0: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
dbd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
dbe0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
dbf0: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
dc00: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
dc10: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
dc20: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
dc30: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
dc40: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
dc50: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
dc60: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
dc70: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
dc80: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
dc90: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
dca0: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
dcb0: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
dcc0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
dcd0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
dce0: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
dcf0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
dd00: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
dd10: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
dd20: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
dd30: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
dd40: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
dd50: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
dd60: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
dd70: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
dd80: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
dd90: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
dda0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
ddb0: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
ddc0: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
ddd0: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
dde0: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
ddf0: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
de00: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
de10: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
de20: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
de30: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
de40: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
de50: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
de60: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
de70: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
de80: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
de90: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
dea0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
deb0: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
dec0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
ded0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
dee0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
def0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
df00: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
df10: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
df20: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
df30: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
df40: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
df50: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
df60: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
df70: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
df80: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
df90: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
dfa0: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
dfb0: 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
dfc0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
dfd0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
dfe0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
dff0: 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
e000: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
e010: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
e020: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
e030: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
e040: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
e050: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
e060: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
e070: 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
e080: 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
e090: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
e0a0: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
e0b0: 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
e0c0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
e0d0: 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
e0e0: 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
e0f0: 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
e100: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
e110: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
e120: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
e130: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
e140: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
e150: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
e160: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
e170: 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
e180: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
e190: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
e1a0: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
e1b0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
e1c0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
e1d0: 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
e1e0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
e1f0: 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
e200: 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
e210: 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
e220: 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
e230: 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20  as given no the 
e240: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
e250: 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
e260: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
e270: 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
e280: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
e290: 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
e2a0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
e2b0: 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
e2c0: 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
e2d0: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
e2e0: 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
e2f0: 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
e300: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
e310: 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
e320: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e330: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
e340: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e350: 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
e360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e370: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
e380: 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
e390: 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
e3a0: 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
e3b0: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
e3c0: 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
e3d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
e3e0: 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
e3f0: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
e400: 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
e410: 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
e420: 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
e430: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
e440: 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
e450: 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
e460: 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
e470: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
e480: 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
e490: 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
e4a0: 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
e4b0: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
e4c0: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
e4d0: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
e4e0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
e4f0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
e500: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
e510: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
e520: 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
e530: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
e540: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
e550: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
e560: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
e570: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
e580: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
e590: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
e5a0: 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
e5b0: 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
e5c0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
e5d0: 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
e5e0: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
e5f0: 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
e600: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
e610: 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
e620: 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
e630: 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
e640: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
e650: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
e660: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
e670: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
e680: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
e690: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
e6a0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
e6b0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e6c0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
e6d0: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
e6e0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
e6f0: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
e700: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
e710: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e720: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
e730: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
e740: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
e750: 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
e760: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
e770: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
e780: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e790: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
e7a0: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
e7b0: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
e7c0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
e7d0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
e7e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
e7f0: 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
e800: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
e810: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
e820: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
e830: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
e840: 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
e850: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e860: 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
e870: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
e880: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
e890: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
e8a0: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
e8b0: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
e8c0: 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
e8d0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e8e0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
e8f0: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
e900: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
e910: 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
e920: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
e930: 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
e940: 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
e950: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
e960: 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
e970: 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
e980: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
e990: 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
e9a0: 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
e9b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
e9c0: 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
e9d0: 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
e9e0: 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
e9f0: 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
ea00: 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
ea10: 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
ea20: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
ea30: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
ea40: 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
ea50: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ea60: 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
ea70: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
ea80: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
ea90: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
eaa0: 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
eab0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
eac0: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
ead0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
eae0: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
eaf0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
eb00: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
eb10: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
eb20: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
eb30: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
eb40: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
eb50: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
eb60: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
eb70: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
eb80: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
eb90: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
eba0: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
ebb0: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
ebc0: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
ebd0: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
ebe0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
ebf0: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
ec00: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
ec10: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
ec20: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
ec30: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
ec40: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
ec50: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
ec60: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
ec70: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
ec80: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
ec90: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
eca0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
ecb0: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
ecc0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ecd0: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
ece0: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
ecf0: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
ed00: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
ed10: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
ed20: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
ed30: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
ed40: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
ed50: 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
ed60: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
ed70: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
ed80: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
ed90: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
eda0: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
edb0: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
edc0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
edd0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
ede0: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
edf0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
ee00: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
ee10: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ee20: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
ee30: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
ee40: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
ee50: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
ee60: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
ee70: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
ee80: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
ee90: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
eea0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
eeb0: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
eec0: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
eed0: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
eee0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
eef0: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
ef00: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
ef10: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
ef20: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
ef30: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
ef40: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
ef50: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
ef60: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
ef70: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
ef80: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
ef90: 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
efa0: 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
efb0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
efc0: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
efd0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
efe0: 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
eff0: 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
f000: 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
f010: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
f020: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
f030: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
f040: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
f050: 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
f060: 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
f070: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
f080: 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
f090: 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
f0a0: 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
f0b0: 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
f0c0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
f0d0: 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
f0e0: 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
f0f0: 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
f100: 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
f110: 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
f120: 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
f130: 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
f140: 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
f150: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
f160: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
f170: 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
f180: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
f190: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
f1a0: 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
f1b0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
f1c0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
f1d0: 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
f1e0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
f1f0: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
f200: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
f210: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
f220: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f230: 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
f240: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
f250: 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
f260: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
f270: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
f280: 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
f290: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
f2a0: 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
f2b0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
f2c0: 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
f2d0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
f2e0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
f2f0: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
f300: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
f310: 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
f320: 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
f330: 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
f340: 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
f350: 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
f360: 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
f370: 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
f380: 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
f390: 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
f3a0: 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
f3b0: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
f3c0: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
f3d0: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
f3e0: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
f3f0: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
f400: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
f410: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
f420: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
f430: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
f440: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
f450: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
f460: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
f470: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
f480: 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
f490: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
f4a0: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
f4b0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
f4c0: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
f4d0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  .int sqlite3_ini
f4e0: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69  tialize(void);.i
f4f0: 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
f500: 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  own(void);.int s
f510: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
f520: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
f530: 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
f540: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f550: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
f560: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
f570: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
f580: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
f590: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
f5a0: 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
f5b0: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
f5c0: 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
f5d0: 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
f5e0: 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
f5f0: 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
f600: 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
f610: 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
f620: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
f630: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
f640: 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
f650: 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
f660: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
f670: 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
f680: 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
f690: 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
f6a0: 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
f6b0: 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
f6c0: 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  l needs..**.** T
f6d0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
f6e0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
f6f0: 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
f700: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
f710: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65  n.** must insure
f720: 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
f730: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
f740: 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
f750: 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
f760: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
f770: 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
f780: 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  ng.  Furthermore
f790: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
f7a0: 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ().** may only b
f7b0: 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
f7c0: 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
f7d0: 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
f7e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
f7f0: 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
f800: 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
f810: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f820: 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ()]..** ^If sqli
f830: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
f840: 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
f850: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f860: 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a  ()] and before.*
f870: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
f880: 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77  own()] then it w
f890: 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ill return SQLIT
f8a0: 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74  E_MISUSE..** Not
f8b0: 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
f8c0: 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   ^sqlite3_config
f8d0: 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
f8e0: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
f8f0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
f900: 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
f910: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
f920: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
f930: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
f940: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
f950: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
f960: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
f970: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f980: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
f990: 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
f9a0: 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
f9b0: 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
f9c0: 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
f9d0: 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
f9e0: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
f9f0: 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74   the [configurat
fa00: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
fa10: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
fa20: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
fa30: 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
fa40: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
fa50: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
fa60: 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
fa70: 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
fa80: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
fa90: 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
faa0: 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
fab0: 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
fac0: 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
fad0: 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
fae0: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
faf0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
fb00: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
fb10: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
fb20: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
fb30: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
fb40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
fb50: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
fb60: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
fb70: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
fb80: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
fb90: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
fba0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
fbb0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
fbc0: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
fbd0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
fbe0: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
fbf0: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
fc00: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
fc10: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
fc20: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
fc30: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
fc40: 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
fc50: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
fc60: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
fc70: 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
fc80: 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
fc90: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
fca0: 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
fcb0: 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
fcc0: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
fcd0: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
fce0: 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
fcf0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
fd00: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
fd10: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
fd20: 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
fd30: 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
fd40: 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
fd50: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
fd60: 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
fd70: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
fd80: 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
fd90: 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
fda0: 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
fdb0: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
fdc0: 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
fdd0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
fde0: 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
fdf0: 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
fe00: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
fe10: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
fe20: 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
fe30: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
fe40: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
fe50: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
fe60: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
fe70: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
fe80: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
fe90: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
fea0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
feb0: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
fec0: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
fed0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
fee0: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
fef0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
ff00: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
ff10: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
ff20: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ff30: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
ff40: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ff50: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
ff60: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
ff70: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
ff80: 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
ff90: 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
ffa0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
ffb0: 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
ffc0: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
ffd0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
ffe0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
fff0: 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
10000 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
10010 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
10020 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
10030 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
10040 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
10050 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
10060 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
10070 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
10080 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
10090 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
100a0 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
100b0 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
100c0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
100d0 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
100e0 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
100f0 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
10100 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
10110 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
10120 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
10130 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
10140 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
10150 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
10160 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
10170 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
10180 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
10190 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
101a0 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
101b0 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
101c0 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
101d0 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
101e0 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
101f0 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
10200 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10210 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
10220 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
10230 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
10240 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
10250 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
10260 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
10270 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
10280 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
10290 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
102a0 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
102b0 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
102c0 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
102d0 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
102e0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
102f0 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
10300 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
10310 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
10320 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
10330 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
10340 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
10350 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
10360 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
10370 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
10380 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
10390 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
103a0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
103b0 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
103c0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
103d0 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
103e0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
103f0 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
10400 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
10410 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
10420 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
10430 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
10440 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
10450 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
10460 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
10470 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
10480 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
10490 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
104a0 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
104b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
104c0 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
104d0 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
104e0 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
104f0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
10500 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
10510 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
10520 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
10530 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
10540 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
10550 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
10560 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
10570 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
10580 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
10590 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
105a0 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
105b0 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
105c0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
105d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
105e0 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
105f0 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
10600 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
10610 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
10620 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
10630 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
10640 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
10650 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
10660 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
10670 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
10680 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
10690 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
106a0 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
106b0 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
106c0 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
106d0 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
106e0 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
106f0 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
10700 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
10710 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
10720 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10730 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
10740 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
10750 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
10760 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
10770 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
10780 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
10790 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
107a0 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
107b0 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
107c0 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
107d0 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
107e0 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
107f0 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
10800 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
10810 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
10820 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
10830 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
10840 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
10850 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
10860 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
10870 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
10880 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
10890 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
108a0 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
108b0 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
108c0 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
108d0 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
108e0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
108f0 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
10900 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
10910 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
10920 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
10930 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10940 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
10950 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
10960 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
10970 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
10980 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
10990 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
109a0 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
109b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
109c0 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
109d0 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
109e0 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
109f0 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
10a00 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
10a10 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
10a20 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
10a30 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
10a40 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
10a50 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
10a60 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
10a70 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
10a80 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
10a90 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
10aa0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
10ab0 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
10ac0 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
10ad0 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
10ae0 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
10af0 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
10b00 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
10b10 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
10b20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
10b30 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
10b40 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
10b50 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
10b60 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
10b70 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
10b80 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
10b90 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
10ba0 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
10bb0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
10bc0 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
10bd0 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
10be0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
10bf0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
10c00 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
10c10 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
10c20 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
10c30 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
10c40 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
10c50 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
10c60 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
10c70 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
10c80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
10c90 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
10ca0 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
10cb0 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
10cc0 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
10cd0 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
10ce0 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
10cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
10d00 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
10d10 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
10d20 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
10d30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
10d40 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
10d50 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
10d60 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  {configuration o
10d70 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ption}.**.** The
10d80 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
10d90 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
10da0 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
10db0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
10dc0 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
10dd0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
10de0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
10df0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10e00 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
10e10 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
10e20 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
10e30 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
10e40 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
10e50 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
10e60 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
10e70 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
10e80 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
10e90 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
10ea0 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
10eb0 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
10ec0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
10ed0 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
10ee0 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
10ef0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
10f00 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
10f10 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
10f20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
10f30 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
10f40 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
10f50 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
10f60 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
10f70 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
10f80 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
10f90 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
10fa0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
10fb0 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
10fc0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
10fd0 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
10fe0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
10ff0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
11000 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
11010 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
11020 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
11030 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d  mode] to Single-
11040 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
11050 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
11060 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
11070 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
11080 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
11090 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
110a0 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
110b0 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
110c0 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
110d0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
110e0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
110f0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
11100 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
11110 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
11120 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
11130 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
11140 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74  to change the [t
11150 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66  hreading mode] f
11160 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a  rom its default.
11170 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67  ** value of Sing
11180 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f  le-thread and so
11190 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
111a0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
111b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
111c0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
111d0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
111e0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
111f0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
11200 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
11210 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11220 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
11230 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11240 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
11250 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
11260 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
11270 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
11280 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
11290 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
112a0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
112b0 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20  o Multi-thread. 
112c0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
112d0 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
112e0 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
112f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11300 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
11310 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
11320 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
11330 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
11340 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
11350 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
11360 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
11370 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
11380 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11390 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
113a0 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
113b0 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
113c0 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
113d0 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
113e0 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
113f0 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
11400 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
11410 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
11420 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
11430 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
11440 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
11450 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53  ame time.  ^If S
11460 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11470 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
11480 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11490 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
114a0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
114b0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
114c0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
114d0 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
114e0 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e Multi-thread [
114f0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11500 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
11510 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
11520 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
11530 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
11540 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
11550 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
11560 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69  READ configurati
11570 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
11580 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11590 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
115a0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
115b0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
115c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
115d0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
115e0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
115f0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
11600 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
11610 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
11620 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20   Serialized. In 
11630 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69  other words, thi
11640 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
11650 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
11660 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
11670 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
11680 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
11690 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
116a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
116b0 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
116c0 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
116d0 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
116e0 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
116f0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
11700 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
11710 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
11720 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
11730 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
11740 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
11750 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11760 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
11770 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
11780 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
11790 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
117a0 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
117b0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
117c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
117d0 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
117e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
117f0 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
11800 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
11810 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c  time..** ^If SQL
11820 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11830 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
11840 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
11850 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
11860 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
11870 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
11880 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
11890 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
118a0 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  Serialized [thre
118b0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
118c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
118d0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
118e0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
118f0 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
11900 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
11910 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
11920 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11930 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
11940 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11950 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
11960 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
11970 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
11980 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
11990 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
119a0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
119b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
119c0 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
119d0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
119e0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
119f0 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
11a00 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
11a10 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
11a20 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
11a30 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
11a40 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
11a50 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
11a60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11a70 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
11a80 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
11a90 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
11aa0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
11ab0 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
11ac0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
11ad0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
11ae0 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
11af0 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
11b00 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
11b10 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
11b20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11b30 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
11b40 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11b50 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
11b60 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
11b70 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
11b80 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
11b90 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
11ba0 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
11bb0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
11bc0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
11bd0 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
11be0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
11bf0 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
11c00 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
11c10 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
11c20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61  defined memory a
11c30 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
11c40 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
11c50 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
11c60 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
11c70 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
11c80 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
11c90 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
11ca0 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
11cb0 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
11cc0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
11cd0 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
11ce0 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
11cf0 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a  example. </dd>.*
11d00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11d10 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d  NFIG_MEMSTATUS]]
11d20 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11d30 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
11d40 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
11d50 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
11d60 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
11d70 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70  type int, interp
11d80 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62  reted as a .** b
11d90 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
11da0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
11db0 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
11dc0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
11dd0 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73  ation .** statis
11de0 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
11df0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
11e00 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
11e10 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20  sabled, the .** 
11e20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
11e30 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
11e40 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
11e50 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
11e60 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
11e70 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
11e80 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
11e90 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
11ea0 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
11eb0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
11ec0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
11ed0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
11ee0 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20  3_status()].**  
11ef0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d   </ul>)^.** ^Mem
11f00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
11f10 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e  tatistics are en
11f20 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
11f30 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69   unless SQLite i
11f40 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
11f50 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  th [SQLITE_DEFAU
11f60 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20  LT_MEMSTATUS]=0 
11f70 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65  in which case me
11f80 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
11f90 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
11fa0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
11fb0 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  fault..** </dd>.
11fc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11fd0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20  ONFIG_SCRATCH]] 
11fe0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11ff0 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
12000 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
12010 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
12020 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
12030 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
12040 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
12050 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
12060 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
12070 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
12080 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
12090 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
120a0 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
120b0 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
120c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
120d0 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
120e0 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
120f0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
12100 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
12110 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
12120 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
12130 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20  locations (N).  
12140 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65  The sz.** argume
12150 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c  nt must be a mul
12160 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20  tiple of 16..** 
12170 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
12180 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69  nt must be a poi
12190 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
121a0 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72  e aligned buffer
121b0 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
121c0 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
121d0 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
121e0 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
121f0 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74  e than two scrat
12200 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
12210 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20  hread.  So.** N 
12220 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f  should be set to
12230 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63   twice the expec
12240 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ted maximum numb
12250 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a  er of threads..*
12260 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
12270 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73  ever require a s
12280 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68  cratch buffer th
12290 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20  at is more than 
122a0 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64  6.** times the d
122b0 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
122c0 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  e. ^If SQLite ne
122d0 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
122e0 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
122f0 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
12300 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
12310 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
12320 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
12330 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
12340 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
12350 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
12360 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
12370 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  d.</dd>.**.** [[
12380 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
12390 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
123a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
123b0 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
123c0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
123d0 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
123e0 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
123f0 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
12400 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
12410 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
12420 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
12430 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20  ault page cache 
12440 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
12450 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
12460 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
12470 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
12480 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
12490 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
124a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
124b0 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
124c0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
124d0 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
124e0 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  n..** There are 
124f0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
12500 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20  to this option: 
12510 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62  A pointer to 8-b
12520 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d  yte aligned.** m
12530 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20  emory, the size 
12540 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66  of each page buf
12550 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68  fer (sz), and th
12560 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
12570 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
12580 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
12590 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
125a0 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
125b0 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
125c0 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
125d0 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37  ween 512 and 327
125e0 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c  68) plus a littl
125f0 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68  e extra for each
12600 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e  .** page header.
12610 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64    ^The page head
12620 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f  er size is 20 to
12630 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64   40 bytes depend
12640 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f  ing on.** the ho
12650 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e  st architecture.
12660 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73    ^It is harmles
12670 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
12680 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
12690 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61  .** to make sz a
126a0 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67   little too larg
126b0 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  e.  The first.**
126c0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
126d0 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
126e0 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
126f0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
12700 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
12710 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
12720 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
12730 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
12740 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
12750 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
12760 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
12770 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
12780 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
12790 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f  he.  ^If additio
127a0 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
127b0 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
127c0 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
127d0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
127e0 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
127f0 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
12800 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
12810 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
12820 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
12830 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f  space..** The po
12840 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72  inter in the fir
12850 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
12860 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74  .** be aligned t
12870 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
12880 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
12890 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
128a0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65  QLite.** will be
128b0 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e   undefined.</dd>
128c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
128d0 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
128e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
128f0 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
12900 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
12910 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
12920 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
12930 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
12940 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
12950 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
12960 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12970 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
12980 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
12990 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
129a0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
129b0 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
129c0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
129d0 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
129e0 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38   arguments: An 8
129f0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
12a00 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
12a10 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
12a20 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
12a30 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
12a40 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
12a50 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
12a60 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
12a70 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
12a80 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
12a90 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
12aa0 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
12ab0 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
12ac0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
12ad0 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
12ae0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
12af0 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
12b00 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
12b10 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
12b20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12b30 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
12b40 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
12b50 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  er is not NULL a
12b60 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  nd either [SQLIT
12b70 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
12b80 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
12b90 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
12ba0 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65  are defined, the
12bb0 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
12bc0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
12bd0 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
12be0 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
12bf0 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
12c00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
12c10 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
12c20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
12c30 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
12c40 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
12c50 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
12c60 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
12c70 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
12c80 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
12c90 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
12ca0 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
12cb0 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
12cc0 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
12cd0 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
12ce0 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
12cf0 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
12d00 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
12d10 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
12d20 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12d30 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
12d40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
12d50 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
12d60 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
12d70 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
12d80 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
12d90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
12da0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
12db0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
12dc0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
12dd0 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
12de0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
12df0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
12e00 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
12e10 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
12e20 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65   in place.** the
12e30 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
12e40 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
12e50 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
12e60 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
12e70 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20  e.** content of 
12e80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
12e90 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
12ea0 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
12eb0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
12ec0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
12ed0 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
12ee0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
12ef0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
12f00 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
12f10 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12f20 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
12f30 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
12f40 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
12f50 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
12f60 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
12f70 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
12f80 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
12f90 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12fa0 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
12fb0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
12fc0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12fd0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
12fe0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
12ff0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
13000 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13010 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
13020 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
13030 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
13040 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
13050 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13060 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
13070 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
13080 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
13090 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
130a0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
130b0 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
130c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
130d0 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
130e0 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
130f0 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
13100 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
13110 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
13120 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
13130 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
13140 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
13150 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
13160 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
13170 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
13180 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
13190 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
131a0 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
131b0 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
131c0 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
131d0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
131e0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
131f0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13200 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
13210 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
13220 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
13230 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
13240 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
13250 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
13260 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
13270 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
13280 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
13290 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
132a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
132b0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
132c0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
132d0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
132e0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
132f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13300 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
13310 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13320 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
13330 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
13340 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
13350 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
13360 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65  determine the de
13370 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20  fault.** memory 
13380 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74  allocation for t
13390 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
133a0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e  ory allocator on
133b0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
133c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
133d0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
133e0 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
133f0 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
13400 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
13410 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
13420 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
13430 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
13440 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
13450 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
13460 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  )^  ^(This optio
13470 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69  n sets the.** <i
13480 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
13490 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
134a0 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
134b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
134c0 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33  verb to [sqlite3
134d0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
134e0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
134f0 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
13500 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
13510 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
13520 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
13530 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13550 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
13560 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
13570 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13580 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13590 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
135a0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
135b0 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b  inter to.** an [
135c0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
135d0 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
135e0 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
135f0 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65  ecifies the inte
13600 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75  rface.** to a cu
13610 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
13620 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
13630 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
13640 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
13650 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
13660 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
13670 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
13680 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
13690 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
136a0 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
136b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
136c0 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
136d0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
136e0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
136f0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13700 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
13710 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
13720 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
13730 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53  ods2] object.  S
13740 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20  QLite copies of 
13750 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70  the current.** p
13760 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
13770 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
13780 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
13790 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
137a0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c  E_CONFIG_LOG]] <
137b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
137c0 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
137d0 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  > The SQLITE_CON
137e0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69  FIG_LOG option i
137f0 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
13800 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a  ure the SQLite.*
13810 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20  * global [error 
13820 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53  log]..** (^The S
13830 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
13840 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
13850 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
13860 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
13870 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
13880 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
13890 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
138a0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
138b0 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
138c0 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
138d0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
138e0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
138f0 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
13900 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
13910 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
13920 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
13930 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
13940 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
13950 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
13960 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
13970 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
13980 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
13990 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
139a0 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
139b0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
139c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
139d0 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
139e0 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
139f0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
13a00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
13a10 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
13a20 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
13a30 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
13a40 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
13a50 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
13a60 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
13a70 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
13a80 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
13a90 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
13aa0 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
13ab0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
13ac0 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
13ad0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
13ae0 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
13af0 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
13b00 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
13b10 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
13b20 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
13b30 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
13b40 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
13b50 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
13b60 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
13b70 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
13b80 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
13b90 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
13ba0 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
13bb0 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
13bc0 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
13bd0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
13be0 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
13bf0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
13c00 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
13c10 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
13c20 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
13c30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
13c40 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
13c50 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
13c60 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
13c70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13c80 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53  NFIG_URI]] <dt>S
13c90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
13ca0 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73 20 6f  .** <dd>^(This o
13cb0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
13cc0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
13cd0 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f   type int. If no
13ce0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20  n-zero, then.** 
13cf0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
13d00 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
13d10 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74  . If the paramet
13d20 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  er is zero, then
13d30 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a   URI handling.**
13d40 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
13d50 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49  abled.)^ ^If URI
13d60 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
13d70 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61  bally enabled, a
13d80 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20  ll filenames.** 
13d90 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
13da0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
13db0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
13dc0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
13dd0 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66  ()] or.** specif
13de0 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ied as part of [
13df0 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73  ATTACH] commands
13e00 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
13e10 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64   as URIs, regard
13e20 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68  less.** of wheth
13e30 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53  er or not the [S
13e40 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
13e50 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
13e60 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
13e70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
13e80 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73  pened. ^If it is
13e90 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
13ea0 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  ed, filenames ar
13eb0 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70  e.** only interp
13ec0 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66  reted as URIs if
13ed0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
13ee0 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74  _URI flag is set
13ef0 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74   when the.** dat
13f00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13f10 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79   is opened. ^(By
13f20 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61   default, URI ha
13f30 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
13f40 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20  ly.** disabled. 
13f50 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
13f60 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64  e may be changed
13f70 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69   by compiling wi
13f80 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
13f90 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f  E_USE_URI] symbo
13fa0 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a  l defined.)^.**.
13fb0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13fc0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
13fd0 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c  X_SCAN]] <dt>SQL
13fe0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
13ff0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a  ING_INDEX_SCAN.*
14000 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74 69  * <dd>^This opti
14010 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14020 65 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d 65  e integer argume
14030 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  nt which is inte
14040 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61 20  rpreted as.** a 
14050 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72  boolean in order
14060 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
14070 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
14080 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
14090 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74 61  s for.** full ta
140a0 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65  ble scans in the
140b0 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
140c0 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  .  ^The default 
140d0 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
140e0 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
140f0 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
14100 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
14110 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
14120 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
14130 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
14140 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14150 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
14160 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
14170 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
14180 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
14190 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
141a0 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
141b0 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
141c0 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
141d0 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
141e0 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
141f0 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  ion.** when the 
14200 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
14210 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
14220 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
14230 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
14240 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
14250 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
14260 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
14270 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
14280 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
14290 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
142a0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
142b0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
142c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
142d0 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
142e0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
142f0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
14300 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
14310 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14320 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
14330 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
14340 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
14350 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
14360 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
14370 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
14380 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
14390 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
143a0 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
143b0 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ops..** </dd>.**
143c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
143d0 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
143e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
143f0 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
14400 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
14410 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
14420 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
14430 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
14440 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
14450 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65  QLLOG] pre-proce
14460 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
14470 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
14480 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
14490 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
144a0 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
144b0 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
144c0 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
144d0 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
144e0 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
144f0 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
14500 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
14510 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
14520 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
14530 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
14540 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
14550 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
14560 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
14570 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
14580 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
14590 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
145a0 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
145b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
145c0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
145d0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
145e0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
145f0 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
14600 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
14610 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
14620 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
14630 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
14640 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
14650 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
14660 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
14670 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
14680 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
14690 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
146a0 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
146b0 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
146c0 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
146d0 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
146e0 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
146f0 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
14700 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
14710 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
14720 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
14730 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
14740 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
14750 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
14760 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20  L In this case. 
14770 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75   An example of u
14780 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e  sing this.** con
14790 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
147a0 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  n can be seen in
147b0 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f   the "test_sqllo
147c0 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  g.c" source file
147d0 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e   in.** the canon
147e0 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72  ical SQLite sour
147f0 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a  ce tree.</dd>.**
14800 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14810 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  FIG_MMAP_SIZE]].
14820 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
14830 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a  NFIG_MMAP_SIZE.*
14840 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f  * <dd>^SQLITE_CO
14850 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74  NFIG_MMAP_SIZE t
14860 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20  akes two 64-bit 
14870 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33  integer (sqlite3
14880 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a  _int64) values.*
14890 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64  * that are the d
148a0 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65  efault mmap size
148b0 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61   limit (the defa
148c0 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a  ult setting for.
148d0 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  ** [PRAGMA mmap_
148e0 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d  size]) and the m
148f0 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
14900 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a  map size limit..
14910 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
14920 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f  setting can be o
14930 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63  verridden by eac
14940 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
14950 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65  ction using.** e
14960 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d  ither the [PRAGM
14970 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d  A mmap_size] com
14980 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e  mand, or by usin
14990 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
149a0 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
149b0 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20  ] file control. 
149c0 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61   ^(The maximum a
149d0 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
149e0 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  .** cannot be ch
149f0 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  anged at run-tim
14a00 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68 65 20  e.  Nor may the 
14a10 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
14a20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65 78 63  mmap size.** exc
14a30 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  eed the compile-
14a40 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61  time maximum mma
14a50 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68  p size set by th
14a60 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  e.** [SQLITE_MAX
14a70 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70  _MMAP_SIZE] comp
14a80 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
14a90 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72  )^.** ^If either
14aa0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
14ab0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61  s option is nega
14ac0 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20  tive, then that 
14ad0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63  argument is.** c
14ae0 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f  hanged to its co
14af0 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75  mpile-time defau
14b00 6c 74 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  lt..** </dl>.*/.
14b10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14b20 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
14b30 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
14b40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14b50 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
14b60 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
14b70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14b80 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
14b90 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
14ba0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14bb0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
14bc0 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
14bd0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
14be0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
14bf0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
14c00 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
14c10 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
14c20 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
14c30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
14c40 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
14c50 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
14c60 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
14c70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
14c80 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
14c90 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
14ca0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
14cb0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14cc0 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
14cd0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
14ce0 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
14cf0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14d00 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
14d10 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
14d20 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
14d30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
14d40 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
14d50 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
14d60 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
14d70 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14d80 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
14d90 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
14da0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
14db0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
14dc0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
14dd0 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
14de0 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
14df0 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
14e00 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14e10 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
14e20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
14e30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14e40 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
14e50 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
14e60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14e70 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
14e80 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
14e90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14ea0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
14eb0 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
14ec0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
14ed0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
14ee0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
14ef0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
14f00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14f10 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
14f20 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
14f30 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
14f40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14f50 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
14f60 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
14f70 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
14f80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14f90 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
14fa0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30  NG_INDEX_SCAN 20
14fb0 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
14fc0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14fd0 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32  G_SQLLOG       2
14fe0 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76  1  /* xSqllog, v
14ff0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
15000 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
15010 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f  AP_SIZE    22  /
15020 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  * sqlite3_int64,
15030 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
15040 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
15050 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
15060 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
15070 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
15080 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
15090 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
150a0 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
150b0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
150c0 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
150d0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
150e0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
150f0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
15100 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
15110 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
15120 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
15130 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
15140 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
15150 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
15160 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
15170 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15180 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
15190 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
151a0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
151b0 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
151c0 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
151d0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
151e0 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
151f0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
15200 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
15210 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
15220 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
15230 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
15240 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
15250 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
15260 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
15270 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
15280 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
15290 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
152a0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
152b0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
152c0 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
152d0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
152e0 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
152f0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
15300 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
15310 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
15320 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
15330 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
15340 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
15350 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15360 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
15370 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
15380 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
15390 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
153a0 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
153b0 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
153c0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
153d0 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
153e0 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
153f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
15400 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
15410 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
15420 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
15430 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
15440 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
15450 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
15460 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
15470 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
15480 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15490 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
154a0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
154b0 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
154c0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
154d0 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
154e0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
154f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
15500 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
15510 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
15520 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
15530 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
15540 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
15550 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
15560 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
15570 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
15580 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
15590 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
155a0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
155b0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
155c0 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
155d0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
155e0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
155f0 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
15600 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
15610 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
15620 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
15630 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
15640 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
15650 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
15660 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
15670 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
15680 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
15690 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
156a0 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
156b0 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
156c0 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
156d0 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
156e0 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
156f0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
15700 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
15710 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
15720 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
15730 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
15740 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15750 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
15760 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
15770 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
15780 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
15790 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
157a0 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
157b0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
157c0 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
157d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
157e0 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
157f0 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
15800 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
15810 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
15820 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
15830 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
15840 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
15850 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
15860 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
15870 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
15880 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
15890 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
158a0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
158b0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
158c0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
158d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
158e0 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
158f0 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
15900 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
15910 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
15920 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
15930 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
15940 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
15950 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
15960 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
15970 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
15980 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
15990 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
159a0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
159b0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
159c0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
159d0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
159e0 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
159f0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
15a00 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
15a10 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
15a20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
15a30 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
15a40 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
15a50 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
15a60 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
15a70 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
15a80 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
15a90 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
15aa0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
15ab0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
15ac0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
15ad0 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
15ae0 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
15af0 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
15b00 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
15b10 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
15b20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
15b30 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
15b40 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
15b50 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
15b60 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
15b70 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
15b80 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
15b90 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
15ba0 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
15bb0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
15bc0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
15bd0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
15be0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
15bf0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
15c00 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
15c10 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
15c20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
15c30 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
15c40 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
15c50 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
15c60 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
15c70 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
15c80 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
15c90 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
15ca0 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
15cb0 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
15cc0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
15cd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
15ce0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
15cf0 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f       1001  /* vo
15d00 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
15d10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
15d20 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
15d30 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20  EY     1002  /* 
15d40 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
15d50 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
15d60 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
15d70 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74  ER  1003  /* int
15d80 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
15d90 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
15da0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
15db0 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
15dc0 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
15dd0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
15de0 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
15df0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
15e00 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
15e10 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
15e20 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
15e30 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
15e40 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
15e50 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
15e60 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
15e70 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
15e80 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
15e90 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
15ea0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
15eb0 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
15ec0 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
15ed0 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
15ee0 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
15ef0 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
15f00 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74  in most SQLite t
15f10 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f  ables (except fo
15f20 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  r [WITHOUT ROWID
15f30 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73  ] tables).** has
15f40 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
15f50 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
15f60 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
15f70 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69  e [ROWID | "rowi
15f80 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20  d"]. ^The rowid 
15f90 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
15fa0 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
15fb0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
15fc0 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
15fd0 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
15fe0 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
15ff0 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
16000 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
16010 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
16020 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74  olumns. ^If.** t
16030 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
16040 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49  olumn of type [I
16050 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
16060 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f  EY] then that co
16070 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
16080 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
16090 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   rowid..**.** ^T
160a0 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  he sqlite3_last_
160b0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
160c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
160d0 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
160e0 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65   the .** most re
160f0 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
16100 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
16110 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
16120 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
16130 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
16140 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e  nnection D..** ^
16150 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49  Inserts into [WI
16160 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
16170 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f  les are not reco
16180 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20  rded..** ^If no 
16190 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
161a0 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20  RT]s into rowid 
161b0 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65  tables.** have e
161c0 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
161d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
161e0 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74  nection D, .** t
161f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  hen sqlite3_last
16200 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
16210 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
16220 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
16230 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
16240 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72  hin a trigger or
16250 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75   within a [virtu
16260 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74  al table].** met
16270 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72  hod, then this r
16280 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75  outine will retu
16290 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  rn the [rowid] o
162a0 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
162b0 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73  * row as long as
162c0 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
162d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
162e0 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e  thod is running.
162f0 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
16300 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
16310 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
16320 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65   ends, the value
16330 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79   returned .** by
16340 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
16350 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74  verts to what it
16360 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20   was before the 
16370 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
16380 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68  al.** table meth
16390 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a  od began.)^.**.*
163a0 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
163b0 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
163c0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
163d0 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
163e0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
163f0 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
16400 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
16410 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
16420 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
16430 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
16440 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
16450 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
16460 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
16470 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
16480 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
16490 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
164a0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
164b0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
164c0 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
164d0 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
164e0 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
164f0 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
16500 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
16510 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
16520 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
16530 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
16540 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
16550 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
16560 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
16570 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
16580 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
16590 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
165a0 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
165b0 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
165c0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
165d0 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
165e0 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
165f0 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
16600 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
16610 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
16620 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
16630 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
16640 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
16650 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
16660 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
16670 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
16680 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
16690 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
166a0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
166b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
166c0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
166d0 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
166e0 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
166f0 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
16700 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
16710 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
16720 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
16730 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
16740 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
16750 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
16760 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
16770 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
16780 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
16790 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
167a0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
167b0 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
167c0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
167d0 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
167e0 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
167f0 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
16800 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
16810 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
16820 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
16830 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
16840 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
16850 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
16860 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
16870 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
16880 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
16890 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
168a0 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
168b0 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
168c0 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69   changed.** or i
168d0 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
168e0 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
168f0 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
16900 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
16910 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ** on the [datab
16920 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
16930 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
16940 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
16950 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e  ..** ^(Only chan
16960 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
16970 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
16980 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c  by the [INSERT],
16990 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72   [UPDATE],.** or
169a0 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
169b0 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
169c0 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
169d0 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
169e0 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f   triggers or [fo
169f0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
16a00 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
16a10 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a  ed.)^ Use the.**
16a20 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
16a30 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
16a40 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ion to find the 
16a50 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
16a60 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75  changes.** inclu
16a70 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
16a80 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20  sed by triggers 
16a90 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20  and foreign key 
16aa0 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  actions..**.** ^
16ab0 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
16ac0 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c  w that are simul
16ad0 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54  ated by an [INST
16ae0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a  EAD OF trigger].
16af0 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
16b00 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74  ed.  Only real t
16b10 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65  able changes are
16b20 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
16b30 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  ^(A "row change"
16b40 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
16b50 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
16b60 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
16b70 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
16b80 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
16b90 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
16ba0 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
16bb0 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
16bc0 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
16bd0 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
16be0 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
16bf0 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
16c00 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
16c10 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
16c20 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
16c30 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
16c40 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
16c50 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
16c60 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67  )^.**.** A "trig
16c70 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20  ger context" is 
16c80 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75  a scope of execu
16c90 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73  tion that begins
16ca0 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74   and.** ends wit
16cb0 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20  h the script of 
16cc0 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  a [CREATE TRIGGE
16cd0 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a  R | trigger]. .*
16ce0 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65  * Most SQL state
16cf0 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61  ments are.** eva
16d00 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f  luated outside o
16d10 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20  f any trigger.  
16d20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70  This is the "top
16d30 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67   level".** trigg
16d40 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20  er context.  If 
16d50 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20  a trigger fires 
16d60 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
16d70 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69  el, a.** new tri
16d80 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20  gger context is 
16d90 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20  entered for the 
16da0 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74  duration of that
16db0 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e   one.** trigger.
16dc0 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72    Subtriggers cr
16dd0 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73  eate subcontexts
16de0 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74   for their durat
16df0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ion..**.** ^Call
16e00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
16e10 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
16e20 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
16e30 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
16e40 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
16e50 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
16e60 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
16e70 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
16e80 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
16e90 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
16ea0 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
16eb0 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
16ec0 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
16ed0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
16ee0 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
16ef0 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
16f00 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c   ^Thus, when cal
16f10 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  led from the top
16f20 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e   level, this fun
16f30 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
16f40 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
16f50 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
16f60 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
16f70 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
16f80 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f  ETE.** that also
16f90 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65   occurred at the
16fa0 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57   top level.  ^(W
16fb0 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
16fc0 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20  f a trigger,.** 
16fd0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
16fe0 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
16ff0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  can be called to
17000 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
17010 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
17020 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
17030 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
17040 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
17050 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
17060 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
17070 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65  body of the same
17080 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77   trigger..** How
17090 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72  ever, the number
170a0 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
170b0 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
170c0 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  es.** caused by 
170d0 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63  subtriggers sinc
170e0 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65  e those have the
170f0 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29  ir own context.)
17100 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
17110 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
17120 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
17130 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
17140 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
17150 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
17160 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
17170 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
17180 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
17190 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
171a0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
171b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
171c0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
171d0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
171e0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
171f0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
17200 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
17210 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
17220 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
17230 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
17240 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
17250 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
17260 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
17270 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
17280 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
17290 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
172a0 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
172b0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
172c0 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
172d0 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
172e0 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
172f0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
17300 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
17310 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20  pened..** ^(The 
17320 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62  count returned b
17330 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
17340 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64  changes() includ
17350 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a  es all changes.*
17360 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41  * from all [CREA
17370 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
17380 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61  gger] contexts a
17390 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  nd changes made 
173a0 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  by.** [foreign k
173b0 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77  ey actions]. How
173c0 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
173d0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
173e0 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
173f0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52   to implement [R
17400 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
17410 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
17420 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
17430 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52  ocessing, or [DR
17440 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73  OP TABLE] proces
17450 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f  sing.  The.** co
17460 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
17470 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65  lude rows of vie
17480 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20  ws that fire an 
17490 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
174a0 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20  ger],.** though 
174b0 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f  if the INSTEAD O
174c0 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20  F trigger makes 
174d0 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f  changes of its o
174e0 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65  wn, those change
174f0 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  s .** are counte
17500 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  d.)^.** ^The sql
17510 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
17520 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f  es() function co
17530 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73  unts the changes
17540 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74   as soon as.** t
17550 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
17560 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
17570 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
17580 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
17590 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65  ndle.** is passe
175a0 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
175b0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
175c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
175d0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
175e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
175f0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
17600 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
17610 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
17620 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
17630 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
17640 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
17650 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
17660 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
17670 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
17680 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17690 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
176a0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
176b0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
176c0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
176d0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
176e0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
176f0 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
17700 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
17710 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
17720 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
17730 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
17740 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
17750 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e  ng Query.**.** ^
17760 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
17770 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
17780 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
17790 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
177a0 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
177b0 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
177c0 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
177d0 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
177e0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
177f0 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
17800 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
17810 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
17820 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
17830 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
17840 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
17850 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
17860 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
17870 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
17880 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
17890 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
178a0 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
178b0 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
178c0 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
178d0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
178e0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
178f0 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
17900 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
17910 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
17920 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
17930 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17940 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
17950 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
17960 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
17970 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
17980 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
17990 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
179a0 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
179b0 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
179c0 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
179d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
179e0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
179f0 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
17a00 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
17a10 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
17a20 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
17a30 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
17a40 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
17a50 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
17a60 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
17a70 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
17a80 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
17a90 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
17aa0 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
17ab0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
17ac0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
17ad0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
17ae0 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
17af0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
17b00 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
17b10 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
17b20 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
17b30 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
17b40 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
17b50 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
17b60 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
17b70 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
17b80 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
17b90 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
17ba0 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
17bb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
17bc0 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
17bd0 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
17be0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
17bf0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
17c00 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
17c10 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
17c20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
17c30 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
17c40 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
17c50 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
17c60 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
17c70 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
17c80 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
17c90 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
17ca0 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
17cb0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
17cc0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
17cd0 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
17ce0 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
17cf0 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
17d00 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
17d10 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
17d20 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
17d30 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
17d40 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
17d50 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
17d60 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
17d70 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
17d80 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
17d90 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
17da0 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
17db0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
17dc0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
17dd0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
17de0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
17df0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
17e00 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
17e10 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
17e20 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
17e30 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73  terrupt()].** is
17e40 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
17e50 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
17e60 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
17e70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
17e80 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
17e90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17ea0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
17eb0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
17ec0 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
17ed0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
17ee0 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
17ef0 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
17f00 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
17f10 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
17f20 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
17f30 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
17f40 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
17f50 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
17f60 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
17f70 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
17f80 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
17f90 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
17fa0 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
17fb0 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
17fc0 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
17fd0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
17fe0 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
17ff0 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
18000 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
18010 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
18020 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
18030 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
18040 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
18050 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
18060 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
18070 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
18080 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
18090 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
180a0 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
180b0 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
180c0 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
180d0 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
180e0 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
180f0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
18100 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
18110 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
18120 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
18130 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
18140 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
18150 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
18160 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
18170 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
18180 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
18190 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
181a0 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
181b0 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
181c0 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
181d0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
181e0 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
181f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
18200 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
18210 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
18220 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
18230 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
18240 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
18250 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
18260 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
18270 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
18280 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
18290 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
182a0 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
182b0 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
182c0 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
182d0 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
182e0 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
182f0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
18300 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
18310 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
18320 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
18330 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
18340 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
18350 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
18360 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
18370 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
18380 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
18390 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
183a0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
183b0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
183c0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
183d0 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
183e0 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
183f0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
18400 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
18410 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
18420 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
18430 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
18440 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
18450 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
18460 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
18470 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
18480 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
18490 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
184a0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
184b0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
184c0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
184d0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
184e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
184f0 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
18500 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
18510 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
18520 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
18530 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
18540 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
18550 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
18560 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
18570 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
18580 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
18590 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
185a0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
185b0 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
185c0 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
185d0 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
185e0 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
185f0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
18600 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
18610 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
18620 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
18630 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
18640 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
18650 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
18660 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
18670 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
18680 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
18690 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
186a0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
186b0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
186c0 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
186d0 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
186e0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
186f0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
18700 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
18710 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
18720 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
18730 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
18740 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
18750 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
18760 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
18770 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
18780 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
18790 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
187a0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
187b0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
187c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
187d0 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
187e0 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
187f0 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
18800 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
18810 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
18820 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
18830 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
18840 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
18850 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
18860 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
18870 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
18880 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
18890 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
188a0 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
188b0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
188c0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
188d0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
188e0 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
188f0 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
18900 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
18910 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
18920 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
18930 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
18940 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
18950 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
18960 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
18970 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
18980 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
18990 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
189a0 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
189b0 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
189c0 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
189d0 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
189e0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
189f0 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
18a00 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
18a10 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
18a20 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
18a30 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
18a40 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
18a50 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
18a60 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
18a70 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
18a80 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
18a90 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
18aa0 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
18ab0 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
18ac0 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
18ad0 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
18ae0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
18af0 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
18b00 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
18b10 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
18b20 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
18b30 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
18b40 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
18b50 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
18b60 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
18b70 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
18b80 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
18b90 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
18ba0 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
18bb0 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
18bc0 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
18bd0 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
18be0 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
18bf0 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
18c00 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
18c10 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
18c20 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
18c30 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
18c40 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
18c50 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
18c60 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
18c70 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
18c80 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
18c90 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
18ca0 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
18cb0 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
18cc0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
18cd0 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
18ce0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
18cf0 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
18d00 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
18d10 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
18d20 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
18d30 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
18d40 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
18d50 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
18d60 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
18d70 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
18d80 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
18d90 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
18da0 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
18db0 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
18dc0 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
18dd0 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
18de0 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
18df0 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
18e00 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
18e10 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
18e20 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
18e30 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
18e40 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
18e50 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
18e60 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
18e70 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
18e80 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
18e90 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
18ea0 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
18eb0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
18ec0 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
18ed0 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
18ee0 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
18ef0 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
18f00 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
18f10 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
18f20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
18f30 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
18f40 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
18f50 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
18f60 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
18f70 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
18f80 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
18f90 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
18fa0 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
18fb0 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
18fc0 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
18fd0 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
18fe0 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
18ff0 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
19000 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
19010 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
19020 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
19030 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
19040 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
19050 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
19060 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
19070 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
19080 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
19090 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
190a0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
190b0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
190c0 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
190d0 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
190e0 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
190f0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
19100 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
19110 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
19120 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
19130 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
19140 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
19150 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
19160 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
19170 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
19180 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
19190 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
191a0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
191b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
191c0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
191d0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
191e0 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
191f0 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
19200 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
19210 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
19220 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
19230 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
19240 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19250 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
19260 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
19270 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
19280 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
19290 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
192a0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
192b0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
192c0 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
192d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
192e0 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
192f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
19300 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
19310 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
19320 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
19330 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
19340 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
19350 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
19360 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
19370 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
19380 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
19390 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
193a0 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
193b0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
193c0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
193d0 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
193e0 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
193f0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
19400 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
19410 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
19420 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
19430 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
19440 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
19450 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
19460 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
19470 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
19480 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
19490 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
194a0 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
194b0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
194c0 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
194d0 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
194e0 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
194f0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
19500 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
19510 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
19520 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
19530 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19540 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65  on] any any give
19550 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
19560 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
19570 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
19580 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
19590 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
195a0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
195b0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
195c0 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
195d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
195e0 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69   cleared.)^.*/.i
195f0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
19600 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
19610 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
19620 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
19630 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
19640 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
19650 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
19660 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
19670 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
19680 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
19690 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
196a0 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
196b0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
196c0 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
196d0 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
196e0 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
196f0 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
19700 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
19710 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
19720 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
19730 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
19740 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
19750 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
19760 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
19770 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
19780 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
19790 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
197a0 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
197b0 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
197c0 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
197d0 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
197e0 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
197f0 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
19800 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
19810 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
19820 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
19830 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
19840 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
19850 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
19860 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
19870 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
19880 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
19890 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
198a0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
198b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
198c0 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
198d0 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
198e0 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
198f0 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
19900 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
19910 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
19920 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
19930 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
19940 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
19950 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
19960 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
19970 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
19980 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
19990 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
199a0 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
199b0 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
199c0 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
199d0 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
199e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
199f0 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
19a00 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
19a10 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
19a20 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
19a30 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
19a40 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
19a50 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
19a60 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
19a70 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
19a80 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
19a90 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
19aa0 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
19ab0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
19ac0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
19ad0 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
19ae0 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
19af0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
19b00 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
19b10 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
19b20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
19b30 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
19b40 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
19b50 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
19b60 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
19b70 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
19b80 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
19b90 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
19ba0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
19bb0 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
19bc0 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
19bd0 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
19be0 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
19bf0 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
19c00 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
19c10 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
19c20 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
19c30 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
19c40 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
19c50 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
19c60 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
19c70 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
19c80 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
19c90 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
19ca0 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
19cb0 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
19cc0 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
19cd0 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
19ce0 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
19cf0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
19d00 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
19d10 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
19d20 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
19d30 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
19d40 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
19d50 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
19d60 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
19d70 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
19d80 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
19d90 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
19da0 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
19db0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
19dc0 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
19dd0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
19de0 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
19df0 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
19e00 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
19e10 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
19e20 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
19e30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19e40 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
19e50 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
19e60 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
19e70 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
19e80 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
19e90 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
19ea0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
19eb0 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
19ec0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
19ed0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
19ee0 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
19ef0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
19f00 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
19f10 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
19f20 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
19f30 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
19f40 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
19f50 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
19f60 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
19f70 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
19f80 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
19f90 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
19fa0 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
19fb0 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
19fc0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
19fd0 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
19fe0 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
19ff0 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
1a000 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
1a010 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
1a020 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a030 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
1a040 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
1a050 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
1a060 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1a070 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
1a080 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1a090 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
1a0a0 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
1a0b0 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
1a0c0 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
1a0d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1a0e0 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
1a0f0 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
1a100 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
1a110 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
1a120 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
1a130 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1a140 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
1a150 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
1a160 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
1a170 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
1a180 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
1a190 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
1a1a0 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
1a1b0 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
1a1c0 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
1a1d0 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
1a1e0 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
1a1f0 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
1a200 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
1a210 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
1a220 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
1a230 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
1a240 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
1a250 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
1a260 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1a270 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1a280 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
1a290 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
1a2a0 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
1a2b0 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
1a2c0 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
1a2d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1a2e0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
1a2f0 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
1a300 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
1a310 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
1a320 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
1a330 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
1a340 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
1a350 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1a360 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
1a370 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
1a380 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
1a390 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1a3a0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
1a3b0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1a3c0 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
1a3d0 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
1a3e0 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
1a3f0 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
1a400 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
1a410 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
1a420 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
1a430 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
1a440 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
1a450 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1a460 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
1a470 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
1a480 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
1a490 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
1a4a0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
1a4b0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
1a4c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1a4d0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
1a4e0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1a4f0 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
1a500 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
1a510 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
1a520 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
1a530 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
1a540 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
1a550 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1a560 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
1a570 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
1a580 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
1a590 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
1a5a0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1a5b0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1a5c0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
1a5d0 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
1a5e0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
1a5f0 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
1a600 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
1a610 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
1a620 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1a630 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
1a640 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
1a650 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
1a660 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
1a670 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
1a680 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
1a690 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
1a6a0 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
1a6b0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1a6c0 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
1a6d0 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
1a6e0 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
1a6f0 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
1a700 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
1a710 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
1a720 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
1a730 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
1a740 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
1a750 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
1a760 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
1a770 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
1a780 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
1a790 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
1a7a0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
1a7b0 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
1a7c0 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
1a7d0 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
1a7e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
1a7f0 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
1a800 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
1a810 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
1a820 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
1a830 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
1a840 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
1a850 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
1a860 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
1a870 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
1a880 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
1a890 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
1a8a0 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
1a8b0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
1a8c0 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
1a8d0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
1a8e0 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
1a8f0 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
1a900 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
1a910 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
1a920 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
1a930 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
1a940 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1a950 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
1a960 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
1a970 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
1a980 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
1a990 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
1a9a0 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
1a9b0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
1a9c0 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
1a9d0 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
1a9e0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1a9f0 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
1aa00 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
1aa10 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
1aa20 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
1aa30 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
1aa40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1aa50 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
1aa60 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
1aa70 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
1aa80 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1aa90 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
1aaa0 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
1aab0 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
1aac0 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
1aad0 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
1aae0 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
1aaf0 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
1ab00 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1ab10 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
1ab20 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
1ab30 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
1ab40 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
1ab50 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
1ab60 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
1ab70 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
1ab80 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
1ab90 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1aba0 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
1abb0 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
1abc0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
1abd0 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
1abe0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
1abf0 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
1ac00 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
1ac10 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
1ac20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
1ac30 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
1ac40 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
1ac50 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
1ac60 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
1ac70 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
1ac80 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
1ac90 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
1aca0 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
1acb0 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
1acc0 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
1acd0 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
1ace0 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
1acf0 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
1ad00 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1ad10 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1ad20 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
1ad30 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
1ad40 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
1ad50 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1ad60 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
1ad70 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
1ad80 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1ad90 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1ada0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1adb0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1adc0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1add0 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1ade0 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1adf0 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
1ae00 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1ae10 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1ae20 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1ae30 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1ae40 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1ae50 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
1ae60 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
1ae70 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
1ae80 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
1ae90 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
1aea0 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
1aeb0 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
1aec0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1aed0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1aee0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1aef0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1af00 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
1af10 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
1af20 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1af30 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
1af40 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
1af50 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
1af60 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
1af70 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
1af80 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
1af90 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1afa0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1afb0 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1afc0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1afd0 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
1afe0 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
1aff0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1b000 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
1b010 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
1b020 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
1b030 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
1b040 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
1b050 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
1b060 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
1b070 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
1b080 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
1b090 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
1b0a0 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
1b0b0 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
1b0c0 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
1b0d0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
1b0e0 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
1b0f0 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
1b100 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
1b110 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
1b120 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
1b130 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
1b140 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1b150 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
1b160 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
1b170 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
1b180 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
1b190 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
1b1a0 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
1b1b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1b1c0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1b1d0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1b1e0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1b1f0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1b200 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
1b210 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1b220 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1b230 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1b240 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1b250 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1b260 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1b270 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
1b280 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
1b290 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1b2a0 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
1b2b0 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
1b2c0 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
1b2d0 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
1b2e0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
1b2f0 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
1b300 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
1b310 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
1b320 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
1b330 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
1b340 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
1b350 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
1b360 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
1b370 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
1b380 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
1b390 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
1b3a0 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a  ing.)^.*/.char *
1b3b0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1b3c0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
1b3d0 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1b3e0 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
1b3f0 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1b400 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
1b410 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1b420 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
1b430 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
1b440 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
1b450 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1b460 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
1b470 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1b480 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
1b490 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
1b4a0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
1b4b0 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
1b4c0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
1b4d0 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
1b4e0 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
1b4f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
1b500 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
1b510 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
1b520 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
1b530 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
1b540 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
1b550 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
1b560 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
1b570 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
1b580 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
1b590 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
1b5a0 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
1b5b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b5c0 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
1b5d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1b5e0 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
1b5f0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
1b600 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
1b610 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
1b620 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
1b630 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1b640 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
1b650 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
1b660 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
1b670 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
1b680 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1b690 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
1b6a0 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
1b6b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1b6c0 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
1b6d0 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
1b6e0 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
1b6f0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
1b700 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1b710 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1b720 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1b730 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1b740 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1b750 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1b760 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1b770 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1b780 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1b790 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1b7a0 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1b7b0 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1b7c0 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1b7d0 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1b7e0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1b7f0 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1b800 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1b810 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1b820 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1b830 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1b840 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1b850 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1b860 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1b870 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1b880 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1b890 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1b8a0 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1b8b0 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1b8c0 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1b8d0 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1b8e0 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1b8f0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1b900 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1b910 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1b920 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1b930 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1b940 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1b950 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1b960 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1b970 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1b980 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1b990 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1b9a0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1b9b0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
1b9c0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
1b9d0 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
1b9e0 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
1b9f0 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
1ba00 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
1ba10 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
1ba20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1ba30 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
1ba40 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
1ba50 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
1ba60 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
1ba70 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72  .)^ ^ If the fir
1ba80 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1ba90 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1baa0 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
1bab0 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
1bac0 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
1bad0 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
1bae0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1baf0 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73  oc(N) where N is
1bb00 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1bb10 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1bb20 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
1bb30 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
1bb40 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1bb50 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20  e3_realloc() is 
1bb60 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
1bb70 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
1bb80 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
1bb90 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
1bba0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1bbb0 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20  free(P) where P 
1bbc0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
1bbd0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1bbe0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
1bbf0 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
1bc00 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
1bc10 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
1bc20 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
1bc30 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
1bc40 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
1bc50 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74  LL if sufficient
1bc60 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61   memory is unava
1bc70 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
1bc80 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
1bc90 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1bca0 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
1bcb0 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
1bcc0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1bcd0 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
1bce0 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
1bcf0 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
1bd00 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1bd10 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e  te3_realloc() an
1bd20 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
1bd30 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
1bd40 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1bd50 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
1bd60 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
1bd70 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1bd80 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
1bd90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  d..**.** ^The me
1bda0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
1bdb0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1bdc0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
1bdd0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
1bde0 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
1bdf0 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
1be00 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
1be10 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
1be20 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
1be30 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
1be40 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
1be50 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
1be60 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
1be70 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
1be80 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
1be90 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
1bea0 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
1beb0 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
1bec0 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
1bed0 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
1bee0 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
1bef0 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
1bf00 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
1bf10 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
1bf20 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
1bf30 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
1bf40 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
1bf50 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
1bf60 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1bf70 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
1bf80 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
1bf90 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1bfa0 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f  .7.10, the Windo
1bfb0 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
1bfc0 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20  layer called.** 
1bfd0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
1bfe0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
1bff0 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
1c000 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
1c010 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
1c020 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1c030 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
1c040 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
1c050 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
1c060 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1c070 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
1c080 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
1c090 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
1c0a0 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65  cation errors we
1c0b0 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
1c0c0 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65  .** they were re
1c0d0 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
1c0e0 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
1c0f0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
1c100 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
1c110 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
1c120 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
1c130 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
1c140 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1c150 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
1c160 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
1c170 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
1c180 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
1c190 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
1c1a0 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
1c1b0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1c1c0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
1c1d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c1e0 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
1c1f0 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
1c200 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
1c210 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
1c220 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
1c230 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
1c240 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
1c250 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
1c260 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
1c270 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1c280 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
1c290 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1c2a0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1c2b0 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
1c2c0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1c2d0 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
1c2e0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1c2f0 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  free(void*);../*
1c300 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1c310 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
1c320 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
1c330 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
1c340 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
1c350 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
1c360 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
1c370 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
1c380 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
1c390 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
1c3a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1c3b0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
1c3c0 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
1c3d0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
1c3e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1c3f0 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
1c400 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1c410 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
1c420 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1c430 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1c440 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
1c450 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
1c460 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
1c470 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
1c480 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1c490 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1c4a0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1c4b0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
1c4c0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
1c4d0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1c4e0 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
1c4f0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1c500 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
1c510 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
1c520 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1c530 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1c540 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1c550 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1c560 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
1c570 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
1c580 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
1c590 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
1c5a0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1c5b0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
1c5c0 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
1c5d0 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
1c5e0 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
1c5f0 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
1c600 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
1c610 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
1c620 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
1c630 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
1c640 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
1c650 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
1c660 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
1c670 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1c680 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
1c690 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
1c6a0 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
1c6b0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1c6c0 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
1c6d0 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1c6e0 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
1c6f0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1c700 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
1c710 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1c720 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
1c730 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
1c740 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1c750 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
1c760 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
1c770 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1c780 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
1c790 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
1c7a0 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
1c7b0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
1c7c0 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
1c7d0 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
1c7e0 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
1c7f0 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
1c800 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
1c810 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
1c820 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
1c830 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
1c840 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
1c850 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
1c860 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
1c870 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
1c880 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
1c890 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
1c8a0 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
1c8b0 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
1c8c0 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
1c8d0 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
1c8e0 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
1c8f0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1c900 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
1c910 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
1c920 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
1c930 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
1c940 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
1c950 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
1c960 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
1c970 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
1c980 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
1c990 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
1c9a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
1c9b0 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20  invoked (either 
1c9c0 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79  internally or by
1c9d0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
1c9e0 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73  ion) the PRNG is
1c9f0 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
1ca00 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
1ca10 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52  d.** from the xR
1ca20 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
1ca30 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
1ca40 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1ca50 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c  ject..** ^On all
1ca60 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
1ca70 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65  cations, the pse
1ca80 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
1ca90 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
1caa0 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
1cab0 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
1cac0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
1cad0 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
1cae0 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f  ** method..*/.vo
1caf0 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
1cb00 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
1cb10 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
1cb20 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
1cb30 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
1cb40 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
1cb50 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1cb60 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
1cb70 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1cb80 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
1cb90 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1cba0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
1cbb0 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
1cbc0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
1cbd0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1cbe0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1cbf0 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
1cc00 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
1cc10 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
1cc20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1cc30 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1cc40 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
1cc50 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
1cc60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1cc70 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
1cc80 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1cc90 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
1cca0 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
1ccb0 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
1ccc0 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
1ccd0 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
1cce0 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
1ccf0 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
1cd00 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
1cd10 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1cd20 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
1cd30 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
1cd40 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
1cd50 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1cd60 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
1cd70 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
1cd80 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
1cd90 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
1cda0 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
1cdb0 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
1cdc0 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
1cdd0 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
1cde0 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
1cdf0 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
1ce00 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
1ce10 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
1ce20 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
1ce30 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1ce40 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
1ce50 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
1ce60 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1ce70 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1ce80 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
1ce90 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1cea0 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
1ceb0 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
1cec0 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
1ced0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
1cee0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1cef0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1cf00 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
1cf10 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
1cf20 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1cf30 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
1cf40 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
1cf50 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1cf60 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
1cf70 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
1cf80 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
1cf90 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
1cfa0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1cfb0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
1cfc0 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
1cfd0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1cfe0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1cff0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1d000 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
1d010 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1d020 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1d030 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
1d040 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
1d050 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
1d060 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
1d070 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1d080 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d090 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
1d0a0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
1d0b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
1d0c0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1d0d0 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
1d0e0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
1d0f0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
1d100 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1d110 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
1d120 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
1d130 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
1d140 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
1d150 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
1d160 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
1d170 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
1d180 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
1d190 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
1d1a0 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
1d1b0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1d1c0 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
1d1d0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
1d1e0 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
1d1f0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1d200 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
1d210 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1d220 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
1d230 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
1d240 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1d250 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1d260 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
1d270 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1d280 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
1d290 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
1d2a0 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
1d2b0 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
1d2c0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
1d2d0 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
1d2e0 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
1d2f0 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
1d300 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
1d310 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
1d320 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
1d330 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
1d340 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
1d350 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
1d360 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
1d370 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
1d380 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
1d390 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1d3a0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
1d3b0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1d3c0 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
1d3d0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
1d3e0 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
1d3f0 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
1d400 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
1d410 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
1d420 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
1d430 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
1d440 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
1d450 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
1d460 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
1d470 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
1d480 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
1d490 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
1d4a0 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
1d4b0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
1d4c0 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
1d4d0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1d4e0 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
1d4f0 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
1d500 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
1d510 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
1d520 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
1d530 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
1d540 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
1d550 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
1d560 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
1d570 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
1d580 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
1d590 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
1d5a0 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
1d5b0 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
1d5c0 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
1d5d0 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
1d5e0 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
1d5f0 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
1d600 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
1d610 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
1d620 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
1d630 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
1d640 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
1d650 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
1d660 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
1d670 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
1d680 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
1d690 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
1d6a0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
1d6b0 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
1d6c0 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
1d6d0 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
1d6e0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
1d6f0 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
1d700 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
1d710 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
1d720 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
1d730 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
1d740 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
1d750 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
1d760 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
1d770 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
1d780 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
1d790 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
1d7a0 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
1d7b0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
1d7c0 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
1d7d0 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
1d7e0 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
1d7f0 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
1d800 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
1d810 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
1d820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1d830 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
1d840 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
1d850 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1d860 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
1d870 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
1d880 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
1d890 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
1d8a0 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
1d8b0 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
1d8c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
1d8d0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1d8e0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
1d8f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1d900 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
1d910 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
1d920 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
1d930 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1d940 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1d950 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
1d960 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
1d970 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1d980 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1d990 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1d9a0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1d9b0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1d9c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1d9d0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1d9e0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1d9f0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1da00 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
1da10 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1da20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
1da30 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
1da40 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
1da50 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
1da60 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
1da70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
1da80 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
1da90 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
1daa0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
1dab0 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
1dac0 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
1dad0 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
1dae0 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
1daf0 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
1db00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1db10 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
1db20 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
1db30 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1db40 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
1db50 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
1db60 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1db70 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
1db80 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
1db90 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
1dba0 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
1dbb0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
1dbc0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1dbd0 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
1dbe0 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
1dbf0 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
1dc00 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1dc10 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
1dc20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1dc30 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
1dc40 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
1dc50 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
1dc60 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
1dc70 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
1dc80 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
1dc90 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
1dca0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
1dcb0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1dcc0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1dcd0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
1dce0 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
1dcf0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1dd00 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
1dd10 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1dd20 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1dd30 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1dd40 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1dd50 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
1dd60 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
1dd70 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
1dd80 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
1dd90 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
1dda0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
1ddb0 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
1ddc0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
1ddd0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
1dde0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1ddf0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1de00 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
1de10 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
1de20 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
1de30 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
1de40 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
1de50 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
1de60 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54  used as a [SQLIT
1de70 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74  E_ROLLBACK | ret
1de80 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f  urn code].** fro
1de90 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
1dea0 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
1deb0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
1dec0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ded0 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
1dee0 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
1def0 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
1df00 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
1df10 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
1df20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
1df30 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
1df40 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
1df50 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
1df60 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1df70 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
1df80 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1df90 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1dfa0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
1dfb0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
1dfc0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
1dfd0 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
1dfe0 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
1dff0 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
1e000 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
1e010 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1e020 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
1e030 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1e040 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
1e050 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
1e060 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
1e070 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
1e080 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
1e090 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
1e0a0 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
1e0b0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
1e0c0 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
1e0d0 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
1e0e0 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
1e0f0 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
1e100 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
1e110 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
1e120 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
1e130 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
1e140 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
1e150 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
1e160 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
1e170 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
1e180 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
1e190 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
1e1a0 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
1e1b0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1e1c0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68  parameter.  ^(Th
1e1d0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
1e1e0 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
1e1f0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1e200 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1e210 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
1e220 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
1e230 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
1e240 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70  e.)^  ^The 6th p
1e250 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1e260 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e270 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
1e280 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
1e290 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
1e2a0 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
1e2b0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
1e2c0 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
1e2d0 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
1e2e0 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
1e2f0 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
1e300 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
1e310 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
1e320 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e330 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e340 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
1e350 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
1e360 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
1e370 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1e380 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
1e390 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
1e3a0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1e3b0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1e3c0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1e3d0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1e3e0 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
1e3f0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1e400 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1e410 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1e420 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
1e430 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1e440 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1e450 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e460 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1e470 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
1e480 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1e490 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1e4a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e4b0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1e4c0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
1e4d0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1e4e0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1e4f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e500 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1e510 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
1e520 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1e530 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e540 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e550 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
1e560 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
1e570 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1e580 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1e590 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e5a0 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
1e5b0 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
1e5c0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1e5d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e5e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e5f0 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
1e600 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
1e610 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e620 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e630 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e640 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
1e650 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
1e660 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1e670 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1e680 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e690 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
1e6a0 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
1e6b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1e6c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1e6d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e6e0 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
1e6f0 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
1e700 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1e710 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1e720 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e730 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
1e740 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
1e750 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1e760 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e770 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1e780 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
1e790 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
1e7a0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1e7b0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1e7c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1e7d0 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
1e7e0 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
1e7f0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1e800 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e810 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1e820 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1e830 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
1e840 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1e850 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1e860 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1e870 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
1e880 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
1e890 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1e8a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e8b0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
1e8c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1e8d0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
1e8e0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1e8f0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1e900 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
1e910 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
1e920 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
1e930 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
1e940 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
1e950 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
1e960 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
1e970 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1e980 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1e990 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e9a0 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
1e9b0 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
1e9c0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
1e9d0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1e9e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e9f0 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
1ea00 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
1ea10 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
1ea20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1ea30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ea40 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
1ea50 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
1ea60 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1ea70 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
1ea80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ea90 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
1eaa0 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
1eab0 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
1eac0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ead0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1eae0 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
1eaf0 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
1eb00 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
1eb10 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1eb20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1eb30 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
1eb40 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
1eb50 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
1eb60 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1eb70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1eb80 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
1eb90 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
1eba0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
1ebb0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ebc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ebd0 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
1ebe0 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
1ebf0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1ec00 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ec10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1ec20 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
1ec30 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
1ec40 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
1ec50 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
1ec60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1ec70 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
1ec80 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
1ec90 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1eca0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1ecb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
1ecc0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
1ecd0 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
1ece0 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
1ecf0 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
1ed00 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
1ed10 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
1ed20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
1ed30 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
1ed40 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
1ed50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
1ed60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ed70 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
1ed80 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  r used */../*.**
1ed90 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
1eda0 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
1edb0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1edc0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1edd0 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
1ede0 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
1edf0 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
1ee00 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
1ee10 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
1ee20 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
1ee30 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
1ee40 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
1ee50 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
1ee60 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
1ee70 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
1ee80 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
1ee90 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
1eea0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
1eeb0 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
1eec0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
1eed0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
1eee0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
1eef0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
1ef00 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
1ef10 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
1ef20 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
1ef30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
1ef40 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
1ef50 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
1ef60 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
1ef70 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
1ef80 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
1ef90 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
1efa0 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
1efb0 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
1efc0 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
1efd0 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
1efe0 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
1eff0 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
1f000 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
1f010 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ^.**.** The [SQL
1f020 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
1f030 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
1f040 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  me option can be
1f050 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a   used to limit.*
1f060 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * the length of 
1f070 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
1f080 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74  ] expansion in t
1f090 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c  he output of sql
1f0a0 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a  ite3_trace()..**
1f0b0 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
1f0c0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1f0d0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1f0e0 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
1f0f0 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
1f100 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
1f110 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
1f120 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
1f130 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
1f140 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
1f150 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
1f160 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
1f170 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
1f180 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
1f190 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
1f1a0 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
1f1b0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
1f1c0 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
1f1d0 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
1f1e0 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
1f1f0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
1f200 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
1f210 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
1f220 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
1f230 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
1f240 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
1f250 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
1f260 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
1f270 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
1f280 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
1f290 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
1f2a0 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
1f2b0 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
1f2c0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
1f2d0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
1f2e0 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
1f2f0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
1f300 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
1f310 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
1f320 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
1f330 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1f340 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  Lite..*/.void *s
1f350 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
1f360 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
1f370 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
1f380 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
1f390 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
1f3a0 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
1f3b0 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
1f3c0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
1f3d0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
1f3e0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
1f3f0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
1f400 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f410 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
1f420 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ss Callbacks.**.
1f430 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1f440 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1f450 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
1f460 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
1f470 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
1f480 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
1f490 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
1f4a0 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
1f4b0 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
1f4c0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1f4d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
1f4e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1f4f0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
1f500 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1f510 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
1f520 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
1f530 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
1f540 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
1f550 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
1f560 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
1f570 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
1f580 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
1f590 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
1f5a0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
1f5b0 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
1f5c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
1f5d0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
1f5e0 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69  N is the approxi
1f5f0 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a  mate number of .
1f600 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
1f610 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
1f620 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
1f630 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
1f640 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
1f650 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
1f660 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e  llback X.  ^If N
1f670 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e   is less than on
1f680 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  e then the progr
1f690 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69  ess.** handler i
1f6a0 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
1f6b0 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
1f6c0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1f6d0 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
1f6e0 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
1f6f0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1f700 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
1f710 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
1f720 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
1f730 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
1f740 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
1f750 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
1f760 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
1f770 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1f780 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
1f790 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
1f7a0 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
1f7b0 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
1f7c0 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
1f7d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
1f7e0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1f7f0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1f800 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
1f810 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
1f820 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
1f830 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
1f840 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
1f850 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
1f860 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
1f870 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
1f880 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
1f890 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
1f8a0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1f8b0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1f8c0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1f8d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f8e0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1f8f0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1f900 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
1f910 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1f920 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1f930 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1f940 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1f950 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1f960 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1f970 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1f980 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1f990 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
1f9a0 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
1f9b0 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
1f9c0 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
1f9d0 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
1f9e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f9f0 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
1fa00 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1fa10 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
1fa20 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
1fa30 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
1fa40 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
1fa50 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
1fa60 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1fa70 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
1fa80 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
1fa90 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
1faa0 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
1fab0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1fac0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
1fad0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
1fae0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
1faf0 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
1fb00 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
1fb10 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
1fb20 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
1fb30 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
1fb40 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
1fb50 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
1fb60 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
1fb70 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
1fb80 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
1fb90 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
1fba0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
1fbb0 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
1fbc0 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
1fbd0 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
1fbe0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
1fbf0 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
1fc00 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
1fc10 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
1fc20 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
1fc30 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1fc40 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
1fc50 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
1fc60 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
1fc70 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
1fc80 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
1fc90 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
1fca0 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
1fcb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1fcc0 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
1fcd0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
1fce0 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
1fcf0 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
1fd00 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
1fd10 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
1fd20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
1fd30 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
1fd40 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
1fd50 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1fd60 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
1fd70 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
1fd80 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
1fd90 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1fda0 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69  UTF-8 if.** sqli
1fdb0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
1fdc0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1fdd0 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a  is called and.**
1fde0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1fdf0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1fe00 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   if sqlite3_open
1fe10 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a  16() is used..**
1fe20 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
1fe30 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
1fe40 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
1fe50 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
1fe60 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
1fe70 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
1fe80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1fe90 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
1fea0 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
1feb0 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
1fec0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
1fed0 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
1fee0 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
1fef0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
1ff00 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
1ff10 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
1ff20 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
1ff30 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
1ff40 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
1ff50 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
1ff60 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
1ff70 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
1ff80 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
1ff90 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
1ffa0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
1ffb0 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
1ffc0 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
1ffd0 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
1ffe0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
1fff0 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
20000 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
20010 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
20020 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
20030 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
20040 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
20050 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
20060 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
20070 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
20080 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
20090 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
200a0 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
200b0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
200c0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
200d0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
200e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
200f0 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
20100 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
20110 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
20120 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
20130 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
20140 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
20150 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
20160 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
20170 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
20180 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
20190 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
201a0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
201b0 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
201c0 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
201d0 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
201e0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
201f0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
20200 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
20210 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
20220 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
20230 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
20240 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
20250 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
20260 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
20270 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
20280 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
20290 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
202a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
202b0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
202c0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
202d0 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
202e0 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
202f0 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
20300 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
20310 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
20320 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
20330 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
20340 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
20350 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
20360 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
20370 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
20380 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
20390 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
203a0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
203b0 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
203c0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
203d0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
203e0 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
203f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
20400 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
20410 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
20420 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
20430 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
20440 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
20450 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
20460 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
20470 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
20480 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
20490 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
204a0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
204b0 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
204c0 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
204d0 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
204e0 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
204f0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
20500 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
20510 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
20520 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
20530 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
20540 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
20550 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
20560 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
20570 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
20580 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
20590 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
205a0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
205b0 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
205c0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
205d0 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
205e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
205f0 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
20600 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
20610 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
20620 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
20630 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
20640 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
20650 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
20660 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
20670 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
20680 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
20690 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
206a0 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
206b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
206c0 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
206d0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
206e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
206f0 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
20700 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
20710 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
20720 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
20730 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
20740 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
20750 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
20760 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
20770 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
20780 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
20790 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
207a0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
207b0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
207c0 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
207d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
207e0 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
207f0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
20800 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
20810 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
20820 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
20830 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
20840 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
20850 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
20860 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
20870 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
20880 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
20890 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
208a0 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
208b0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
208c0 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
208d0 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
208e0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
208f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
20900 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
20910 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
20920 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
20930 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
20940 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
20950 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
20960 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
20970 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
20980 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
20990 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
209a0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
209b0 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
209c0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
209d0 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
209e0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
209f0 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
20a00 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
20a10 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
20a20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
20a30 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
20a40 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
20a50 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
20a60 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
20a70 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
20a80 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
20a90 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
20aa0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
20ab0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
20ac0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
20ad0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
20ae0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
20af0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
20b00 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
20b10 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
20b20 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
20b30 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
20b40 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
20b50 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
20b60 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
20b70 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
20b80 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
20b90 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
20ba0 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
20bb0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
20bc0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
20bd0 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
20be0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
20bf0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
20c00 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
20c10 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
20c20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
20c30 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
20c40 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
20c50 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
20c60 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
20c70 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
20c80 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
20c90 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
20ca0 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
20cb0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
20cc0 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
20cd0 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
20ce0 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
20cf0 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
20d00 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
20d10 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
20d20 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
20d30 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
20d40 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
20d50 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
20d60 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
20d70 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
20d80 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
20d90 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
20da0 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
20db0 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
20dc0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
20dd0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
20de0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
20df0 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
20e00 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
20e10 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
20e20 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
20e30 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
20e40 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
20e50 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
20e60 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
20e70 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
20e80 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
20e90 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
20ea0 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
20eb0 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
20ec0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
20ed0 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
20ee0 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
20ef0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
20f00 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
20f10 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
20f20 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
20f30 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
20f40 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
20f50 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
20f60 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
20f70 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
20f80 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
20f90 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
20fa0 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
20fb0 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
20fc0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
20fd0 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
20fe0 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
20ff0 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
21000 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
21010 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
21020 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
21030 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
21040 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
21050 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
21060 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
21070 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
21080 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73   .** ^On windows
21090 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
210a0 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
210b0 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
210c0 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
210d0 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
210e0 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  ")..**.** [[core
210f0 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
21100 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
21110 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
21120 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
21130 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
21140 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
21150 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
21160 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
21170 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
21180 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
21190 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
211a0 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
211b0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
211c0 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  ree query parame
211d0 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
211e0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
211f0 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
21200 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
21210 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
21220 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
21230 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
21240 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
21250 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
21260 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
21270 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
21280 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
21290 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
212a0 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
212b0 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
212c0 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
212d0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
212e0 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
212f0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
21300 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
21310 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
21320 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
21330 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
21340 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
21350 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
21360 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
21370 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
21380 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
21390 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
213a0 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
213b0 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
213c0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
213d0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
213e0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
213f0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
21400 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
21410 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
21420 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
21430 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
21440 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
21450 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
21460 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
21470 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
21480 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
21490 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
214a0 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
214b0 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
214c0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
214d0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
214e0 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
214f0 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
21500 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
21510 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
21520 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
21530 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
21540 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
21550 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21560 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
21570 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
21580 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
21590 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
215a0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
215b0 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
215c0 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
215d0 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
215e0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
215f0 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
21600 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
21610 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
21620 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
21630 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
21640 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
21650 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
21660 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
21670 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
21680 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
21690 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
216a0 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
216b0 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
216c0 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
216d0 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
216e0 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
216f0 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
21700 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
21710 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
21720 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
21730 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
21740 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
21750 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
21760 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
21770 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
21780 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
21790 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
217a0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
217b0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
217c0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
217d0 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
217e0 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
217f0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
21800 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
21810 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
21820 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
21830 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
21840 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
21850 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
21860 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
21870 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
21880 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
21890 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
218a0 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
218b0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
218c0 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
218d0 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
218e0 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
218f0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
21900 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
21910 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
21920 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
21930 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
21940 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
21950 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
21960 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
21970 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
21980 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
21990 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
219a0 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71  any behavior req
219b0 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e  uested by settin
219c0 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  g.**     SQLITE_
219d0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
219e0 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e  E or SQLITE_OPEN
219f0 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61  _SHAREDCACHE fla
21a00 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  g..** </ul>.**.*
21a10 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
21a20 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
21a30 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
21a40 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
21a50 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
21a60 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
21a70 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
21a80 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
21a90 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
21aa0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
21ab0 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
21ac0 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
21ad0 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
21ae0 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
21af0 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
21b00 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
21b10 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
21b20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
21b30 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
21b40 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
21b50 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
21b60 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
21b70 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
21b80 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
21b90 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
21ba0 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
21bb0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
21bc0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
21bd0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
21be0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
21bf0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
21c00 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
21c10 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
21c20 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
21c30 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
21c40 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
21c50 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
21c60 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
21c70 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
21c80 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
21c90 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
21ca0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
21cb0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
21cc0 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
21cd0 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
21ce0 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
21cf0 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
21d00 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
21d10 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
21d20 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
21d30 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
21d40 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
21d50 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
21d60 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
21d70 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
21d80 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
21d90 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
21da0 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
21db0 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
21dc0 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
21dd0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
21de0 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
21df0 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
21e00 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
21e10 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
21e20 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
21e30 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
21e40 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
21e50 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
21e60 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
21e70 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
21e80 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
21e90 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
21ea0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
21eb0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
21ec0 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
21ed0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
21ee0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
21ef0 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
21f00 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
21f10 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
21f20 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
21f30 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
21f40 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
21f50 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
21f60 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
21f70 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
21f80 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
21f90 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
21fa0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
21fb0 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
21fc0 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64  =unix-nolock <td
21fd0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70  >.**          Op
21fe0 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  en file "/home/f
21ff0 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73  red/data.db". Us
22000 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  e the special VF
22010 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e  S "unix-nolock".
22020 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
22030 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
22040 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
22050 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
22060 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
22070 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
22080 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
22090 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
220a0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
220b0 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
220c0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
220d0 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
220e0 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
220f0 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
22100 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
22110 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
22120 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
22130 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
22140 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
22150 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
22160 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
22170 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
22180 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
22190 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
221a0 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
221b0 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
221c0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
221d0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
221e0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
221f0 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
22200 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
22210 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
22220 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
22230 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
22240 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
22250 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
22260 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
22270 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
22280 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
22290 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
222a0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
222b0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
222c0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
222d0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
222e0 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
222f0 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
22300 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
22310 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
22320 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
22330 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
22340 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
22350 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
22360 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
22370 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
22380 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
22390 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
223a0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
223b0 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
223c0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
223d0 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
223e0 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
223f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
22400 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
22410 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
22420 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
22430 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
22440 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
22450 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
22460 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
22470 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
22480 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
22490 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
224a0 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
224b0 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
224c0 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
224d0 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
224e0 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
224f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
22500 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
22510 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e  directory].*/.in
22520 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
22530 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
22540 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
22550 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
22560 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
22570 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
22580 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
22590 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
225a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
225b0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
225c0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
225d0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
225e0 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
225f0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
22600 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
22610 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
22620 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
22630 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
22640 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
22650 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
22660 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
22670 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
22680 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
22690 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
226a0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
226b0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
226c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
226d0 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
226e0 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
226f0 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
22700 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
22710 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22720 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
22730 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
22740 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
22750 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
22760 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
22770 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
22780 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
22790 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
227a0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
227b0 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
227c0 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
227d0 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
227e0 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
227f0 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
22800 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
22810 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
22820 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
22830 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
22840 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
22850 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
22860 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
22870 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
22880 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
22890 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
228a0 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
228b0 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
228c0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
228d0 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
228e0 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
228f0 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
22900 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
22910 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
22920 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
22930 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
22940 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
22950 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
22960 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
22970 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
22980 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
22990 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
229a0 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
229b0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
229c0 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
229d0 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
229e0 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
229f0 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
22a00 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
22a10 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
22a20 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
22a30 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
22a40 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
22a50 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
22a60 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
22a70 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
22a80 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
22a90 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
22aa0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
22ab0 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
22ac0 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
22ad0 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
22ae0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
22af0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
22b00 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
22b10 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
22b20 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
22b30 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
22b40 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
22b50 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
22b60 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
22b70 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
22b80 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
22b90 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
22ba0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
22bb0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
22bc0 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
22bd0 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
22be0 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
22bf0 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
22c00 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
22c10 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
22c20 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
22c30 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
22c40 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
22c50 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
22c60 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
22c70 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
22c80 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
22c90 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
22ca0 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
22cb0 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
22cc0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
22cd0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
22ce0 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
22cf0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
22d00 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
22d10 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
22d20 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
22d30 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
22d40 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
22d50 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
22d60 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
22d70 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
22d80 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
22d90 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
22da0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
22db0 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
22dc0 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
22dd0 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
22de0 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
22df0 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
22e00 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
22e10 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
22e20 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
22e30 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
22e40 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
22e50 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
22e60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
22e70 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
22e80 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
22e90 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
22ea0 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
22eb0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
22ec0 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
22ed0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
22ee0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
22ef0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
22f00 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
22f10 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
22f20 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
22f30 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
22f40 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
22f50 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
22f60 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71  *zParam);.int sq
22f70 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
22f80 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
22f90 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
22fa0 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
22fb0 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f  fault);.sqlite3_
22fc0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
22fd0 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
22fe0 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
22ff0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
23000 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
23010 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
23020 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a  And Messages.**.
23030 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
23040 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
23050 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
23060 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
23070 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
23080 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
23090 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
230a0 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
230b0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
230c0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
230d0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
230e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
230f0 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
23100 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
23110 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
23120 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
23130 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
23140 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
23150 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
23160 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   undefined.  ^Th
23170 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
23180 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
23190 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
231a0 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
231b0 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
231c0 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
231d0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
231e0 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
231f0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
23200 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
23210 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
23220 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
23230 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
23240 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
23250 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
23260 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
23270 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
23280 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
23290 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
232a0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
232b0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
232c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
232d0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
232e0 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
232f0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
23300 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
23310 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
23320 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
23330 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
23340 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
23350 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
23360 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
23370 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
23380 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
23390 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
233a0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
233b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
233c0 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65  e3_errstr() inte
233d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
233e0 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  e English-langua
233f0 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20  ge text.** that 
23400 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72  describes the [r
23410 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20  esult code], as 
23420 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  UTF-8..** ^(Memo
23430 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
23440 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
23450 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
23460 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64  nternally.** and
23470 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65   must not be fre
23480 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
23490 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57  ation)^..**.** W
234a0 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
234b0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
234c0 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
234d0 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
234e0 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
234f0 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
23500 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
23510 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
23520 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
23530 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
23540 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
23550 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
23560 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
23570 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
23580 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
23590 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
235a0 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
235b0 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
235c0 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
235d0 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
235e0 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
235f0 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
23600 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
23610 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
23620 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
23630 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
23640 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
23650 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
23660 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
23670 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
23680 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
23690 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
236a0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
236b0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
236c0 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
236d0 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
236e0 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
236f0 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
23700 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
23710 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
23720 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
23730 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
23740 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
23750 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
23760 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
23770 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
23780 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
23790 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
237a0 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
237b0 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
237c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
237d0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
237e0 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
237f0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
23800 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
23810 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
23820 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
23830 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
23840 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
23850 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  g16(sqlite3*);.c
23860 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
23870 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
23880 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23890 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
238a0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
238b0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
238c0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
238d0 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
238e0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
238f0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
23900 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
23910 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
23920 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
23930 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
23940 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
23950 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
23960 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
23970 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
23980 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
23990 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
239a0 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
239b0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
239c0 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
239d0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
239e0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
239f0 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
23a00 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
23a10 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
23a20 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
23a30 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
23a40 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
23a50 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
23a60 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
23a70 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
23a80 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
23a90 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
23aa0 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
23ab0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
23ac0 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
23ad0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
23ae0 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
23af0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
23b00 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
23b10 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
23b20 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
23b30 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
23b40 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
23b50 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
23b60 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
23b70 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
23b80 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
23b90 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
23ba0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
23bb0 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
23bc0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
23bd0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
23be0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
23bf0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
23c00 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
23c10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
23c20 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a  -time Limits.**.
23c30 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
23c40 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
23c50 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
23c60 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
23c70 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
23c80 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
23c90 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
23ca0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
23cb0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
23cc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23cd0 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
23ce0 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
23cf0 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
23d00 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
23d10 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
23d20 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
23d30 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
23d40 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
23d50 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
23d60 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
23d70 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
23d80 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
23d90 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
23da0 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
23db0 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
23dc0 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
23dd0 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
23de0 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
23df0 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
23e00 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
23e10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
23e20 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
23e30 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
23e40 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
23e50 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
23e60 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
23e70 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
23e80 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
23e90 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
23ea0 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
23eb0 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
23ec0 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
23ed0 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
23ee0 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
23ef0 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
23f00 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
23f10 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
23f20 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
23f30 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
23f40 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
23f50 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
23f60 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
23f70 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
23f80 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
23f90 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
23fa0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
23fb0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
23fc0 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
23fd0 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
23fe0 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
23ff0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
24000 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
24010 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
24020 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
24030 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
24040 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
24050 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
24060 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
24070 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
24080 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
24090 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
240a0 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
240b0 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
240c0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
240d0 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
240e0 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
240f0 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
24100 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
24110 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
24120 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
24130 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
24140 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
24150 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
24160 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
24170 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
24180 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
24190 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
241a0 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
241b0 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
241c0 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
241d0 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
241e0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
241f0 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
24200 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
24210 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
24220 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
24230 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
24240 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
24250 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
24260 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
24270 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
24280 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
24290 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
242a0 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
242b0 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
242c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
242d0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
242e0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
242f0 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
24300 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
24310 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
24320 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
24330 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
24340 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
24350 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
24360 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
24370 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
24380 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
24390 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
243a0 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
243b0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
243c0 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eases..*/.int sq
243d0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
243e0 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
243f0 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
24400 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
24410 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
24420 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
24430 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
24440 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
24450 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
24460 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
24470 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
24480 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
24490 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
244a0 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
244b0 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
244c0 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
244d0 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
244e0 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
244f0 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
24500 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
24510 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
24520 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
24530 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
24540 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
24550 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
24560 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
24570 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e  LIMIT_LENGTH]] ^
24580 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
24590 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
245a0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
245b0 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
245c0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
245d0 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74  able row, in byt
245e0 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  es.<dd>)^.**.** 
245f0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  [[SQLITE_LIMIT_S
24600 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  QL_LENGTH]] ^(<d
24610 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
24620 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
24630 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
24640 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
24650 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
24660 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
24670 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
24680 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c  MIT_COLUMN]] ^(<
24690 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
246a0 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
246b0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
246c0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
246d0 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
246e0 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
246f0 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
24700 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
24710 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
24720 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
24730 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
24740 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
24750 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
24760 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
24770 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  [[SQLITE_LIMIT_E
24780 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  XPR_DEPTH]] ^(<d
24790 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
247a0 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
247b0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
247c0 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
247d0 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
247e0 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
247f0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
24800 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
24810 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74  D_SELECT]] ^(<dt
24820 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
24830 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
24840 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
24850 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
24860 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
24870 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
24880 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
24890 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
248a0 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64  T_VDBE_OP]] ^(<d
248b0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
248c0 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
248d0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
248e0 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
248f0 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
24900 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
24910 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
24920 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
24930 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20  tatement.  This 
24940 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72  limit is not cur
24950 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63  rently.** enforc
24960 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20  ed, though that 
24970 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69  might be added i
24980 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
24990 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
249a0 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  te.</dd>)^.**.**
249b0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
249c0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e  FUNCTION_ARG]] ^
249d0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
249e0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
249f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
24a00 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
24a10 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
24a20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
24a30 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
24a40 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d  LIMIT_ATTACHED]]
24a50 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
24a60 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
24a70 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
24a80 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
24a90 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
24aa0 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
24ab0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
24ac0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
24ad0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a  ATTERN_LENGTH]].
24ae0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
24af0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
24b00 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
24b10 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
24b20 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
24b30 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
24b40 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
24b50 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
24b60 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
24b70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
24b80 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
24b90 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ER]].** ^(<dt>SQ
24ba0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
24bb0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
24bc0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
24bd0 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
24be0 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
24bf0 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
24c00 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
24c10 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  [[SQLITE_LIMIT_T
24c20 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e  RIGGER_DEPTH]] ^
24c30 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
24c40 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
24c50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24c60 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
24c70 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
24c80 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
24c90 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
24ca0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
24cb0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
24cc0 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
24cd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
24ce0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
24cf0 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
24d00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
24d10 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
24d20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
24d30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
24d40 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
24d50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
24d60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
24d70 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
24d80 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
24d90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24da0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
24db0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24dc0 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
24dd0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
24de0 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
24df0 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
24e00 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
24e10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24e20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
24e30 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
24e40 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
24e50 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
24e60 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
24e70 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
24e80 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
24e90 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
24ea0 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
24eb0 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41      10../*.** CA
24ec0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
24ed0 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
24ee0 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  nt.** KEYWORDS: 
24ef0 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  {SQL statement c
24f00 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54  ompiler}.**.** T
24f10 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c  o execute an SQL
24f20 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20   query, it must 
24f30 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65  first be compile
24f40 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f  d into a byte-co
24f50 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  de.** program us
24f60 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ing one of these
24f70 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
24f80 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
24f90 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20  ent, "db", is a 
24fa0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
24fb0 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66  tion] obtained f
24fc0 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73  rom a.** prior s
24fd0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
24fe0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
24ff0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
25000 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  n_v2()] or.** [s
25010 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
25020 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20  .  The database 
25030 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
25040 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c  not have been cl
25050 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
25060 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
25070 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
25080 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
25090 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
250a0 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
250b0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
250c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
250d0 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
250e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
250f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
25100 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
25110 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
25120 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
25130 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
25140 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
25150 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61   ^If the nByte a
25160 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20  rgument is less 
25170 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20  than zero, then 
25180 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
25190 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
251a0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
251b0 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f   ^If nByte is no
251c0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
251d0 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d   it is the maxim
251e0 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  um.** number of 
251f0 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
25200 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42   zSql.  ^When nB
25210 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
25220 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
25230 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
25240 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
25250 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
25260 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
25270 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68  .** the nByte-th
25280 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
25290 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66   comes first. If
252a0 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
252b0 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75  s.** that the su
252c0 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
252d0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
252e0 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61   then there is a
252f0 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72   small.** perfor
25300 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
25310 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20  to be gained by 
25320 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
25330 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
25340 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74  ** is equal to t
25350 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
25360 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
25370 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
25380 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
25390 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79  ul-terminator by
253a0 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76 65  tes as this save
253b0 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61  s SQLite from ha
253c0 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20  ving to.** make 
253d0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e  a copy of the in
253e0 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  put string..**.*
253f0 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
25400 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
25410 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
25420 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
25430 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
25440 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
25450 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
25460 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
25470 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
25480 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
25490 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
254a0 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
254b0 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
254c0 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
254d0 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
254e0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
254f0 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
25500 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
25510 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
25520 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
25530 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
25540 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
25550 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
25560 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
25570 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
25580 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
25590 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
255a0 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
255b0 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
255c0 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
255d0 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
255e0 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
255f0 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
25600 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
25610 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
25620 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
25630 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
25640 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
25650 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
25660 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
25670 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
25680 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
25690 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
256a0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
256b0 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
256c0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
256d0 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
256e0 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
256f0 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
25700 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
25710 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
25720 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
25730 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
25740 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
25750 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
25760 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
25770 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
25780 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
25790 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
257a0 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
257b0 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
257c0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
257d0 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
257e0 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
257f0 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
25800 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
25810 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
25820 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
25830 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
25840 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
25850 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
25860 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
25870 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
25880 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
25890 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
258a0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
258b0 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
258c0 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
258d0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
258e0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
258f0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
25900 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
25910 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
25920 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
25930 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
25940 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
25950 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
25960 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
25970 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
25980 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
25990 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
259a0 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79  t again. As many
259b0 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f   as [SQLITE_MAX_
259c0 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a  SCHEMA_RETRY].**
259d0 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63   retries will oc
259e0 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74  cur before sqlit
259f0 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20  e3_step() gives 
25a00 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  up and returns a
25a10 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69  n error..** </li
25a20 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
25a30 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
25a40 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
25a50 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
25a60 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
25a70 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
25a80 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
25a90 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
25aa0 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
25ab0 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
25ac0 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
25ad0 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
25ae0 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
25af0 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
25b00 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
25b10 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
25b20 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
25b30 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
25b40 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
25b50 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
25b60 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
25b70 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
25b80 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
25b90 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
25ba0 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
25bb0 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
25bc0 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
25bd0 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
25be0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
25bf0 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
25c00 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
25c10 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
25c20 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
25c30 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
25c40 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
25c50 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
25c60 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
25c70 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
25c80 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
25c90 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
25ca0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
25cb0 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
25cc0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
25cd0 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
25ce0 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
25cf0 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
25d00 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
25d10 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
25d20 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
25d30 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
25d40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
25d50 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
25d60 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
25d70 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
25d80 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
25d90 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
25da0 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
25db0 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
25dc0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
25dd0 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
25de0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
25df0 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
25e00 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
25e10 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
25e20 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
25e30 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
25e40 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
25e50 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
25e60 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
25e70 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
25e80 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
25e90 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20  led..** the .** 
25ea0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
25eb0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  /.int sqlite3_pr
25ec0 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
25ed0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
25ee0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
25ef0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
25f00 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
25f10 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
25f20 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
25f30 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
25f40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
25f50 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
25f60 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
25f70 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
25f80 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
25f90 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
25fa0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
25fb0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
25fc0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
25fd0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
25fe0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
25ff0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
26000 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
26010 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
26020 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
26030 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
26040 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
26050 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
26060 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
26070 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
26080 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
26090 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
260a0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
260b0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
260c0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
260d0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
260e0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
260f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
26100 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
26110 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
26120 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
26130 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
26140 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
26150 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
26160 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
26170 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
26180 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
26190 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
261a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
261b0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
261c0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
261d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
261e0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
261f0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
26200 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
26210 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
26220 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
26230 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
26240 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
26250 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
26260 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
26270 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
26280 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
26290 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
262a0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
262b0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
262c0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
262d0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
262e0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
262f0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
26300 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
26310 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
26320 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
26330 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
26340 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
26350 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
26360 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
26370 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
26380 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
26390 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
263a0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
263b0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
263c0 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
263d0 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
263e0 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
263f0 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  SQL.**.** ^This 
26400 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
26410 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
26420 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
26430 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
26440 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
26450 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
26460 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26470 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
26480 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
26490 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
264a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
264b0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
264c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
264d0 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
264e0 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
264f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
26500 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
26510 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
26520 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
26530 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
26540 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54  atabase.**.** ^T
26550 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
26560 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
26570 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
26580 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
26590 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
265a0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
265b0 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
265c0 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
265d0 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
265e0 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
265f0 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
26600 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
26610 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
26620 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
26630 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
26640 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
26650 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
26660 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
26670 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
26680 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
26690 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
266a0 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
266b0 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
266c0 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
266d0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
266e0 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
266f0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
26700 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
26710 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
26720 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
26730 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
26740 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
26750 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
26760 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
26770 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
26780 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
26790 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
267a0 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
267b0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
267c0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
267d0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
267e0 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
267f0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
26800 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
26810 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
26820 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
26830 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
26840 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
26850 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
26860 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
26870 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
26880 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
26890 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
268a0 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
268b0 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
268c0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
268d0 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
268e0 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
268f0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
26900 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
26910 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
26920 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
26930 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
26940 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
26950 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
26960 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
26970 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
26980 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
26990 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
269a0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
269b0 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
269c0 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
269d0 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
269e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
269f0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
26a00 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
26a10 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
26a20 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
26a30 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
26a40 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
26a50 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  k..*/.int sqlite
26a60 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
26a70 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
26a80 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
26a90 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
26aa0 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53   If A Prepared S
26ab0 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65  tatement Has Bee
26ac0 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  n Reset.**.** ^T
26ad0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
26ae0 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63  busy(S) interfac
26af0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
26b00 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65  non-zero) if the
26b10 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
26b20 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62  atement] S has b
26b30 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c  een stepped at l
26b40 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20  east once using 
26b50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
26b60 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f  p(S)] but has no
26b70 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  t run to complet
26b80 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e  ion and/or has n
26b90 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65  ot .** been rese
26ba0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
26bb0 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68  _reset(S)].  ^Th
26bc0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
26bd0 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66  usy(S).** interf
26be0 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73  ace returns fals
26bf0 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c  e if S is a NULL
26c00 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20   pointer.  If S 
26c10 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c  is not a .** NUL
26c20 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73  L pointer and is
26c30 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74   not a pointer t
26c40 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61  o a valid [prepa
26c50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
26c60 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74  * object, then t
26c70 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
26c80 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
26c90 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
26ca0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  e..**.** This in
26cb0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
26cc0 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69  sed in combinati
26cd0 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  on [sqlite3_next
26ce0 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c  _stmt()].** to l
26cf0 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72  ocate all prepar
26d00 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  ed statements as
26d10 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
26d20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e  database .** con
26d30 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65  nection that are
26d40 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e   in need of bein
26d50 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63  g reset.  This c
26d60 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66  an be used,.** f
26d70 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64  or example, in d
26d80 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e  iagnostic routin
26d90 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72  es to search for
26da0 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74   prepared .** st
26db0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  atements that ar
26dc0 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e  e holding a tran
26dd0 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f  saction open..*/
26de0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
26df0 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73  t_busy(sqlite3_s
26e00 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
26e10 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
26e20 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
26e30 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
26e40 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
26e50 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
26e60 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
26e70 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
26e80 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
26e90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
26ea0 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
26eb0 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
26ec0 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
26ed0 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
26ee0 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
26ef0 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
26f00 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
26f10 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
26f20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
26f30 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
26f40 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
26f50 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
26f60 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
26f70 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
26f80 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
26f90 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
26fa0 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
26fb0 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
26fc0 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
26fd0 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
26fe0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
26ff0 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
27000 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
27010 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
27020 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
27030 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
27040 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
27050 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27060 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
27070 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
27080 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
27090 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
270a0 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
270b0 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
270c0 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
270d0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
270e0 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
270f0 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
27100 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
27110 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
27120 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
27130 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72   held.  An inter
27140 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
27150 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
27160 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
27170 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
27180 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
27190 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
271a0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
271b0 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
271c0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
271d0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
271e0 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
271f0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
27200 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
27210 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
27220 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
27230 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
27240 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
27250 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
27260 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
27270 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
27280 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
27290 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
272a0 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
272b0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
272c0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
272d0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
272e0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
272f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27300 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
27310 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
27320 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
27330 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
27340 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
27350 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
27360 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
27370 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
27380 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
27390 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
273a0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
273b0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
273c0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
273d0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
273e0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
273f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
27400 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
27410 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
27420 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
27430 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
27440 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
27450 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
27460 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
27470 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
27480 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
27490 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
274a0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
274b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
274c0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
274d0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
274e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
274f0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
27500 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
27510 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
27520 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
27530 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
27540 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
27550 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
27560 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
27570 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
27580 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
27590 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
275a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
275b0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
275c0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
275d0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
275e0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
275f0 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
27600 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
27610 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
27620 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
27630 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
27640 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
27650 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
27660 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
27670 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
27680 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
27690 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
276a0 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
276b0 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
276c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
276d0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
276e0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
276f0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
27700 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
27710 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
27720 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
27730 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
27740 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
27750 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
27760 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
27770 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
27780 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
27790 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
277a0 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
277b0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
277c0 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
277d0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
277e0 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
277f0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
27800 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
27810 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
27820 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
27830 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
27840 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
27850 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
27860 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
27870 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
27880 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
27890 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
278a0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
278b0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
278c0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
278d0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
278e0 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
278f0 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ding}.**.** ^(In
27900 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
27910 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
27920 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27930 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
27940 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
27950 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
27960 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
27970 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
27980 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
27990 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
279a0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
279b0 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
279c0 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
279d0 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
279e0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
279f0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
27a00 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
27a10 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
27a20 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
27a30 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
27a40 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
27a50 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
27a60 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
27a70 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
27a80 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
27a90 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
27aa0 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
27ab0 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
27ac0 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
27ad0 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
27ae0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
27af0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
27b00 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
27b10 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
27b20 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
27b30 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
27b40 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
27b50 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
27b60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
27b70 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
27b80 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
27b90 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
27ba0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
27bb0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
27bc0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
27bd0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
27be0 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
27bf0 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
27c00 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
27c10 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
27c20 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
27c30 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
27c40 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
27c50 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
27c60 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
27c70 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
27c80 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
27c90 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
27ca0 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
27cb0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
27cc0 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
27cd0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
27ce0 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
27cf0 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
27d00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
27d10 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
27d20 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
27d30 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
27d40 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
27d50 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
27d60 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
27d70 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
27d80 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
27d90 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
27da0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
27db0 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
27dc0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
27dd0 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
27de0 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
27df0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
27e00 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
27e10 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
27e20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
27e30 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
27e40 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
27e50 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
27e60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27e70 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  xt16().** or sql
27e80 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
27e90 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
27ea0 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  er then the four
27eb0 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  th parameter.** 
27ec0 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74  is ignored and t
27ed0 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73  he end result is
27ee0 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c   the same as sql
27ef0 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29  ite3_bind_null()
27f00 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
27f10 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
27f20 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
27f30 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
27f40 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
27f50 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
27f60 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
27f70 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
27f80 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
27f90 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
27fa0 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
27fb0 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
27fc0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
27fd0 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
27fe0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
27ff0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
28000 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
28010 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
28020 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
28030 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
28040 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
28050 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
28060 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
28070 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
28080 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
28090 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
280a0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
280b0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
280c0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
280d0 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
280e0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
280f0 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
28100 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
28110 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
28120 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
28130 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
28140 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
28150 29 20 74 68 65 6e 20 74 68 61 74 20 70 61 72 61  ) then that para
28160 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68  meter must be th
28170 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a  e byte offset.**
28180 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
28190 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20  erminator would 
281a0 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74  occur assuming t
281b0 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e  he string were N
281c0 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64  UL.** terminated
281d0 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
281e0 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61  aracters occur a
281f0 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c  t byte offsets l
28200 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65  ess than .** the
28210 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f   value of the fo
28220 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
28230 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
28240 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77  g string value w
28250 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65  ill.** contain e
28260 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54  mbedded NULs.  T
28270 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  he result of exp
28280 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69  ressions involvi
28290 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69  ng strings.** wi
282a0 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
282b0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
282c0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
282d0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
282e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
282f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
28300 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c  xt(), and.** sql
28310 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
28320 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74  () is a destruct
28330 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
28340 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
28350 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
28360 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
28370 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20  ished with it.  
28380 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
28390 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20  is called.** to 
283a0 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
283b0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76  LOB or string ev
283c0 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  en if the call t
283d0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
283e0 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  lob(),.** sqlite
283f0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f  3_bind_text(), o
28400 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
28410 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20  ext16() fails.  
28420 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
28430 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
28440 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
28450 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
28460 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
28470 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
28480 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
28490 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
284a0 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
284b0 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
284c0 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
284d0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
284e0 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
284f0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
28500 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
28510 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
28520 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
28530 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
28540 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
28550 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
28560 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
28570 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
28580 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
28590 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
285a0 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
285b0 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
285c0 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
285d0 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
285e0 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73  ^A zeroblob uses
285f0 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
28600 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
28610 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
28620 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
28630 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
28640 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
28650 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
28660 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
28670 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
28680 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
28690 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
286a0 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
286b0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
286c0 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
286d0 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
286e0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20  routines..** ^A 
286f0 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
28700 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
28710 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
28720 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
28730 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20  *.** ^If any of 
28740 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
28750 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  _*() routines ar
28760 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  e called with a 
28770 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
28780 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
28790 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
287a0 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20  with a prepared 
287b0 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68  statement for wh
287c0 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
287d0 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
287e0 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63   called more rec
287f0 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69  ently than [sqli
28800 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a  te3_reset()],.**
28810 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77   then the call w
28820 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
28830 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20  TE_MISUSE].  If 
28840 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  any sqlite3_bind
28850 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69  _().** routine i
28860 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70  s passed a [prep
28870 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
28880 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69  that has been fi
28890 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20  nalized, the.** 
288a0 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
288b0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
288c0 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
288d0 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f  ^Bindings are no
288e0 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
288f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
28900 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e  )] routine..** ^
28910 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
28920 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
28930 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
28940 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
28950 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72  ind_* routines r
28960 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
28970 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
28980 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
28990 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67  e] if anything g
289a0 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b  oes wrong..** ^[
289b0 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
289c0 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
289d0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
289e0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
289f0 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e  nge.  ^[SQLITE_N
28a00 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
28a10 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61  d if malloc() fa
28a20 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ils..**.** See a
28a30 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
28a40 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
28a50 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
28a60 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28a70 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
28a80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
28a90 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
28aa0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28ab0 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
28ac0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
28ad0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
28ae0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
28af0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
28b00 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
28b10 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
28b20 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69  ouble);.int sqli
28b30 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
28b40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
28b50 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
28b60 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
28b70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28b80 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
28b90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
28ba0 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
28bb0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74  stmt*, int);.int
28bc0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
28bd0 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
28be0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
28bf0 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  r*, int n, void(
28c00 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
28c10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
28c20 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
28c30 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
28c40 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
28c50 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
28c60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
28c70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
28c80 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
28c90 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
28ca0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
28cb0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
28cc0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
28cd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28ce0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
28cf0 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  L Parameters.**.
28d00 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
28d10 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
28d20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
28d30 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
28d40 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
28d50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28d60 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
28d70 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
28d80 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
28d90 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
28da0 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
28db0 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
28dc0 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
28dd0 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
28de0 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
28df0 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
28e00 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
28e10 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
28e20 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
28e30 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
28e40 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
28e50 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
28e60 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
28e70 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
28e80 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
28e90 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
28ea0 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
28eb0 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
28ec0 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
28ed0 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
28ee0 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
28ef0 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
28f00 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
28f10 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
28f20 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
28f30 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
28f40 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
28f50 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
28f60 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28f70 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
28f80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
28f90 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
28fa0 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
28fb0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28fc0 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
28fd0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
28fe0 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
28ff0 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
29000 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ter.**.** ^The s
29010 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29020 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
29030 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29040 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
29050 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
29060 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
29070 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29080 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
29090 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
290a0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
290b0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
290c0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
290d0 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
290e0 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
290f0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
29100 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
29110 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
29120 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
29130 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
29140 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
29150 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
29160 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
29170 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
29180 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
29190 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
291a0 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
291b0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
291c0 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
291d0 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
291e0 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
291f0 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
29200 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
29210 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
29220 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
29230 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
29240 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
29250 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
29260 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
29270 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
29280 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
29290 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
292a0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
292b0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
292c0 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
292d0 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
292e0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
292f0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
29300 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
29310 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
29320 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
29330 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
29340 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
29350 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
29360 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
29370 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
29380 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
29390 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
293a0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
293b0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
293c0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
293d0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
293e0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
293f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29400 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
29410 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
29420 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29430 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
29440 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
29450 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65  n Name.**.** ^Re
29460 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
29470 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
29480 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
29490 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
294a0 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
294b0 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
294c0 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
294d0 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
294e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
294f0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
29500 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
29510 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
29520 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
29530 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
29540 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
29550 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
29560 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
29570 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
29580 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
29590 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
295a0 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
295b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
295c0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
295d0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
295e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
295f0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
29600 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
29610 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29620 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
29630 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
29640 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
29650 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
29660 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29670 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
29680 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
29690 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
296a0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
296b0 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
296c0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
296d0 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  ement.**.** ^Con
296e0 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
296f0 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
29700 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29710 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
29720 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
29730 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
29740 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
29750 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29760 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
29770 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
29780 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
29790 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
297a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
297b0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
297c0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
297d0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
297e0 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
297f0 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
29800 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
29810 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
29820 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
29830 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
29840 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
29850 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
29860 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
29870 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
29880 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
29890 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
298a0 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
298b0 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
298c0 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
298d0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
298e0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
298f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
29900 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
29910 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
29920 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29930 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
29940 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
29950 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
29960 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
29970 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
29980 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
29990 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
299a0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
299b0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
299c0 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
299d0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
299e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
299f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
29a00 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
29a10 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
29a20 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
29a30 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
29a40 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
29a50 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
29a60 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
29a70 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
29a80 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
29a90 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
29aa0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
29ab0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
29ac0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
29ad0 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
29ae0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
29af0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
29b00 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
29b10 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
29b20 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
29b30 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
29b40 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
29b50 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
29b60 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
29b70 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
29b80 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
29b90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
29ba0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
29bb0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
29bc0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
29bd0 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
29be0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
29bf0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
29c00 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
29c10 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
29c20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
29c30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
29c40 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
29c50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
29c60 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
29c70 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
29c80 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
29c90 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
29ca0 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
29cb0 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
29cc0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
29cd0 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
29ce0 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
29cf0 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
29d00 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
29d10 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
29d20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
29d30 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
29d40 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
29d50 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
29d60 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
29d70 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
29d80 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
29d90 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
29da0 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
29db0 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
29dc0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
29dd0 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
29de0 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
29df0 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
29e00 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
29e10 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  t..*/.const char
29e20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
29e30 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
29e40 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
29e50 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
29e60 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
29e70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29e80 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
29e90 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
29ea0 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
29eb0 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54   Result.**.** ^T
29ec0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
29ed0 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
29ee0 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
29ef0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
29f00 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
29f10 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
29f20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
29f30 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
29f40 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
29f50 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
29f60 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
29f70 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
29f80 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
29f90 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
29fa0 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
29fb0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
29fc0 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
29fd0 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
29fe0 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
29ff0 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
2a000 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
2a010 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
2a020 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
2a030 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
2a040 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2a050 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
2a060 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2a070 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
2a080 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
2a090 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
2a0a0 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
2a0b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
2a0c0 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2a0d0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2a0e0 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2a0f0 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2a100 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2a110 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2a120 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2a130 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2a140 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
2a150 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
2a160 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
2a170 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
2a180 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
2a190 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
2a1a0 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
2a1b0 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
2a1c0 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
2a1d0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2a1e0 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
2a1f0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2a200 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
2a210 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
2a220 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a230 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
2a240 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2a250 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2a260 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
2a270 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2a280 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
2a290 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
2a2a0 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
2a2b0 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
2a2c0 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
2a2d0 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
2a2e0 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
2a2f0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
2a300 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2a310 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2a320 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
2a330 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
2a340 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
2a350 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
2a360 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
2a370 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
2a380 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
2a390 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
2a3a0 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
2a3b0 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
2a3c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2a3d0 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
2a3e0 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
2a3f0 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
2a400 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
2a410 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
2a420 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
2a430 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
2a440 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
2a450 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
2a460 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
2a470 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
2a480 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
2a490 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
2a4a0 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
2a4b0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
2a4c0 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
2a4d0 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
2a4e0 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
2a4f0 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
2a500 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
2a510 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
2a520 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
2a530 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
2a540 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
2a550 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
2a560 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
2a570 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2a580 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2a590 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
2a5a0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2a5b0 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
2a5c0 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
2a5d0 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
2a5e0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2a5f0 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
2a600 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
2a610 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
2a620 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2a630 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2a640 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
2a650 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2a660 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
2a670 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
2a680 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
2a690 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2a6a0 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
2a6b0 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
2a6c0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
2a6d0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2a6e0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
2a6f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2a700 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2a710 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
2a720 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2a730 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2a740 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2a750 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2a760 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2a770 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2a780 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
2a790 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2a7a0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
2a7b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2a7c0 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
2a7d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2a7e0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
2a7f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2a800 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
2a810 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2a820 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2a830 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2a840 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2a850 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2a860 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
2a870 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
2a880 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
2a890 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
2a8a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2a8b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a8c0 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
2a8d0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2a8e0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2a8f0 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
2a900 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
2a910 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
2a920 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
2a930 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
2a940 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
2a950 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
2a960 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
2a970 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2a980 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
2a990 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
2a9a0 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
2a9b0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2a9c0 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
2a9d0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2a9e0 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
2a9f0 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
2aa00 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2aa10 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2aa20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
2aa30 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
2aa40 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2aa50 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
2aa60 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
2aa70 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
2aa80 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
2aa90 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
2aaa0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
2aab0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
2aac0 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
2aad0 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
2aae0 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
2aaf0 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
2ab00 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
2ab10 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
2ab20 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
2ab30 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
2ab40 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
2ab50 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
2ab60 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
2ab70 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
2ab80 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
2ab90 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
2aba0 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
2abb0 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
2abc0 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
2abd0 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
2abe0 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
2abf0 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
2ac00 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
2ac10 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
2ac20 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
2ac30 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
2ac40 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
2ac50 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
2ac60 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
2ac70 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
2ac80 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
2ac90 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
2aca0 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
2acb0 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
2acc0 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
2acd0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
2ace0 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
2acf0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2ad00 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
2ad10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2ad20 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2ad30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
2ad40 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
2ad50 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
2ad60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
2ad70 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
2ad80 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74  tement.**.** Aft
2ad90 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
2ada0 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
2adb0 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
2adc0 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
2add0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2ade0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2adf0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2ae00 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
2ae10 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2ae20 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
2ae30 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
2ae40 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
2ae50 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
2ae60 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2ae70 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
2ae80 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
2ae90 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
2aea0 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
2aeb0 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
2aec0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
2aed0 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
2aee0 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
2aef0 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
2af00 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
2af10 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
2af20 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
2af30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2af40 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
2af50 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2af60 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
2af70 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
2af80 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
2af90 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2afa0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2afb0 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
2afc0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
2afd0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
2afe0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
2aff0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
2b000 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
2b010 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
2b020 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
2b030 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
2b040 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
2b050 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
2b060 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
2b070 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
2b080 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
2b090 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
2b0a0 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
2b0b0 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
2b0c0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
2b0d0 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
2b0e0 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
2b0f0 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
2b100 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
2b110 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
2b120 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
2b130 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
2b140 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
2b150 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
2b160 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
2b170 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
2b180 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
2b190 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
2b1a0 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
2b1b0 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
2b1c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2b1d0 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
2b1e0 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
2b1f0 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
2b200 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
2b210 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
2b220 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
2b230 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
2b240 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
2b250 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
2b260 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78   within an.** ex
2b270 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
2b280 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
2b290 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
2b2a0 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
2b2b0 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
2b2c0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2b2d0 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
2b2e0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
2b2f0 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
2b300 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
2b310 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
2b320 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
2b330 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
2b340 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
2b350 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
2b360 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
2b370 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2b380 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
2b390 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
2b3a0 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
2b3b0 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
2b3c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
2b3d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
2b3e0 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
2b3f0 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
2b400 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
2b410 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
2b420 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
2b430 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
2b440 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
2b450 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
2b460 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
2b470 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
2b480 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
2b490 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2b4a0 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
2b4b0 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
2b4c0 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
2b4d0 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
2b4e0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
2b4f0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
2b500 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
2b510 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
2b520 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
2b530 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
2b540 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
2b550 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
2b560 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
2b570 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
2b580 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
2b590 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
2b5a0 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
2b5b0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
2b5c0 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
2b5d0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2b5e0 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
2b5f0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
2b600 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
2b610 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
2b620 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
2b630 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
2b640 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
2b650 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
2b660 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
2b670 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b680 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
2b690 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b6a0 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
2b6b0 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
2b6c0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2b6d0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
2b6e0 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
2b6f0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2b700 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
2b710 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
2b720 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
2b730 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
2b740 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
2b750 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
2b760 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
2b770 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b780 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
2b790 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
2b7a0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
2b7b0 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
2b7c0 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
2b7d0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
2b7e0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
2b7f0 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
2b800 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
2b810 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
2b820 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
2b830 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2b840 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
2b850 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
2b860 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
2b870 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
2b880 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
2b890 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73  For all versions
2b8a0 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f   of SQLite up to
2b8b0 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33   and including 3
2b8c0 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20  .6.23.1, a call 
2b8d0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
2b8e0 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75  eset()] was requ
2b8f0 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ired after sqlit
2b900 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
2b910 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f  ed anything.** o
2b920 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2b930 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e  E_ROW] before an
2b940 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
2b950 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
2b960 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
2b970 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20  ailure to reset 
2b980 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2b990 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a  tement using .**
2b9a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b9b0 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20  )] would result 
2b9c0 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
2b9d0 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
2b9e0 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  m.** sqlite3_ste
2b9f0 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20  p().  But after 
2ba00 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
2ba10 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
2ba20 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e   began.** callin
2ba30 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2ba40 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ()] automaticall
2ba50 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d  y in this circum
2ba60 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a  stance rather.**
2ba70 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20   than returning 
2ba80 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2ba90 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f    This is not co
2baa0 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61  nsidered a compa
2bab0 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61  tibility.** brea
2bac0 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70  k because any ap
2bad0 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65  plication that e
2bae0 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20  ver receives an 
2baf0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72  SQLITE_MISUSE er
2bb00 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e  ror.** is broken
2bb10 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   by definition. 
2bb20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   The [SQLITE_OMI
2bb30 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d  T_AUTORESET] com
2bb40 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2bb50 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
2bb60 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c  to restore the l
2bb70 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a  egacy behavior..
2bb80 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
2bb90 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
2bba0 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
2bbb0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
2bbc0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
2bbd0 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
2bbe0 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
2bbf0 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
2bc00 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
2bc10 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
2bc20 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
2bc30 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
2bc40 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2bc50 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
2bc60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2bc70 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2bc80 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
2bc90 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
2bca0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
2bcb0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
2bcc0 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
2bcd0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
2bce0 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
2bcf0 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
2bd00 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
2bd10 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
2bd20 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
2bd30 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2bd40 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
2bd50 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
2bd60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
2bd70 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
2bd80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2bd90 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2bda0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2bdb0 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
2bdc0 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
2bdd0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2bde0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2bdf0 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
2be00 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
2be10 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
2be20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
2be30 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
2be40 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
2be50 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
2be60 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
2be70 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2be80 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20  mmended..*/.int 
2be90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
2bea0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2beb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2bec0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2bed0 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
2bee0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2bef0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2bf00 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2bf10 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2bf20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
2bf30 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
2bf40 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2bf50 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
2bf60 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
2bf70 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
2bf80 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
2bf90 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
2bfa0 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
2bfb0 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
2bfc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2bfd0 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
2bfe0 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
2bff0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
2c000 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
2c010 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
2c020 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
2c030 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2c040 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
2c050 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
2c060 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2c070 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2c080 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2c090 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2c0a0 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
2c0b0 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
2c0c0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2c0d0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2c0e0 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
2c0f0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2c100 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
2c110 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
2c120 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
2c130 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2c140 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
2c150 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
2c160 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
2c170 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
2c180 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
2c190 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
2c1a0 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
2c1b0 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
2c1c0 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
2c1d0 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
2c1e0 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
2c1f0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
2c200 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2c210 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2c220 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2c230 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
2c240 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2c250 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c260 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
2c270 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
2c280 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
2c290 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
2c2a0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
2c2b0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
2c2c0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
2c2d0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
2c2e0 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
2c2f0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2c300 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
2c310 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
2c320 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
2c330 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
2c340 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
2c350 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
2c360 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2c370 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
2c380 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
2c390 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
2c3a0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
2c3b0 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
2c3c0 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
2c3d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2c3e0 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
2c3f0 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
2c400 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
2c410 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
2c420 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
2c430 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
2c440 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
2c450 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
2c460 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
2c470 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
2c480 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2c490 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
2c4a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
2c4b0 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
2c4c0 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
2c4d0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2c4e0 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
2c4f0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2c500 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
2c510 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
2c520 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
2c530 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
2c540 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
2c550 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
2c560 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
2c570 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
2c580 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
2c590 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2c5a0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
2c5b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
2c5c0 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
2c5d0 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  et" interface..*
2c5e0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2c5f0 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
2c600 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
2c610 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
2c620 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
2c630 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
2c640 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
2c650 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
2c660 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
2c670 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
2c680 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c690 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
2c6a0 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
2c6b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2c6c0 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
2c6d0 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
2c6e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2c6f0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
2c700 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
2c710 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
2c720 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
2c730 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
2c740 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
2c750 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
2c760 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
2c770 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2c780 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2c790 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
2c7a0 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
2c7b0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2c7c0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
2c7d0 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
2c7e0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2c7f0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2c800 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
2c810 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
2c820 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
2c830 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
2c840 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
2c850 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
2c860 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
2c870 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
2c880 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
2c890 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
2c8a0 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
2c8b0 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
2c8c0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
2c8d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c8e0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
2c8f0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
2c900 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
2c910 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
2c920 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2c930 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
2c940 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
2c950 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
2c960 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2c970 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
2c980 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2c990 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2c9a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2c9b0 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
2c9c0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2c9d0 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
2c9e0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
2c9f0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
2ca00 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2ca10 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
2ca20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2ca30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ca40 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2ca50 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
2ca60 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
2ca70 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
2ca80 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
2ca90 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2caa0 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
2cab0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2cac0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
2cad0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2cae0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
2caf0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2cb00 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
2cb10 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
2cb20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
2cb30 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
2cb40 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
2cb50 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
2cb60 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
2cb70 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2cb80 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
2cb90 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
2cba0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
2cbb0 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
2cbc0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
2cbd0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
2cbe0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2cbf0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2cc00 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
2cc10 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
2cc20 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
2cc30 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
2cc40 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
2cc50 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
2cc60 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
2cc70 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
2cc80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2cc90 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
2cca0 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
2ccb0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2ccc0 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
2ccd0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
2cce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2ccf0 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
2cd00 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2cd10 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2cd20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2cd30 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
2cd40 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2cd50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2cd60 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
2cd70 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2cd80 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2cd90 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
2cda0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2cdb0 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
2cdc0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2cdd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2cde0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2cdf0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2ce00 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
2ce10 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2ce20 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2ce30 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2ce40 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2ce50 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2ce60 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
2ce70 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2ce80 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2ce90 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2cea0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
2ceb0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2cec0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2ced0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2cee0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2cef0 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2cf00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cf10 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20  bytes() returns 
2cf20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
2cf30 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2cf40 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
2cf50 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2cf60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2cf70 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
2cf80 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2cf90 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2cfa0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2cfb0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2cfc0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2cfd0 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
2cfe0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cff0 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
2d000 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2d010 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
2d020 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
2d030 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
2d040 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2d050 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
2d060 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
2d070 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2d080 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
2d090 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2d0a0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2d0b0 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2d0c0 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
2d0d0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2d0e0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2d0f0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2d100 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2d110 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2d120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d130 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
2d140 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
2d150 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2d160 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2d170 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
2d180 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2d190 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
2d1a0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
2d1b0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2d1c0 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
2d1d0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
2d1e0 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
2d1f0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
2d200 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2d210 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
2d220 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
2d230 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2d240 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
2d250 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
2d260 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
2d270 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2d280 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
2d290 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
2d2a0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2d2b0 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
2d2c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2d2d0 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
2d2e0 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
2d2f0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
2d300 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
2d310 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
2d320 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
2d330 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
2d340 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
2d350 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2d360 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  er..**.** ^The o
2d370 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2d380 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2d390 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
2d3a0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2d3b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2d3c0 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72  object.  An unpr
2d3d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d3e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20  value object.** 
2d3f0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2d400 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62   with [sqlite3_b
2d410 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
2d420 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2d430 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
2d440 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
2d450 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2d460 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2d470 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2d480 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2d490 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
2d4a0 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
2d4b0 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
2d4c0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
2d4d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2d4e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2d4f0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
2d500 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
2d510 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e  e_bytes()], then
2d520 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2d530 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2d540 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2d550 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
2d560 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
2d570 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
2d580 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
2d590 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
2d5a0 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
2d5b0 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
2d5c0 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
2d5d0 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
2d5e0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2d5f0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
2d600 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
2d610 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
2d620 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
2d630 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
2d640 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
2d650 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
2d660 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
2d670 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
2d680 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
2d690 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
2d6a0 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
2d6b0 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
2d6c0 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
2d6d0 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
2d6e0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
2d6f0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2d700 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2d710 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
2d720 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2d730 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2d740 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
2d750 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
2d760 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
2d770 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
2d780 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
2d790 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
2d7a0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
2d7b0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
2d7c0 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
2d7d0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2d7e0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
2d7f0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2d800 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
2d810 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
2d820 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2d830 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2d840 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2d850 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
2d860 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2d870 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
2d880 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2d890 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
2d8a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2d8b0 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
2d8c0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
2d8d0 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20  t from float to 
2d8e0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
2d8f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2d900 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2d910 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2d920 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
2d930 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2d940 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2d950 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46    <td> Same as F
2d960 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  LOAT->TEXT.** <t
2d970 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2d980 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2d990 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a  td> Use atoi().*
2d9a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2d9b0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2d9c0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66     <td> Use atof
2d9d0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2d9e0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
2d9f0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
2da00 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
2da10 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2da20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
2da30 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
2da40 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a  hen use atoi().*
2da50 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2da60 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2da70 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2da80 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
2da90 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
2daa0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2dab0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2dac0 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
2dad0 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
2dae0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
2daf0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
2db00 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
2db10 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
2db20 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
2db30 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
2db40 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
2db50 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
2db60 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
2db70 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
2db80 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
2db90 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
2dba0 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
2dbb0 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
2dbc0 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
2dbd0 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
2dbe0 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
2dbf0 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
2dc00 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
2dc10 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
2dc20 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
2dc30 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
2dc40 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
2dc50 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
2dc60 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2dc70 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
2dc80 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2dc90 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
2dca0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2dcb0 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
2dcc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2dcd0 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
2dce0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
2dcf0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
2dd00 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
2dd10 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
2dd20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
2dd30 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
2dd40 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2dd50 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2dd60 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
2dd70 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
2dd80 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
2dd90 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2dda0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2ddb0 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
2ddc0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
2ddd0 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
2dde0 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
2ddf0 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
2de00 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2de10 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2de20 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
2de30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2de40 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
2de50 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2de60 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
2de70 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2de80 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2de90 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2dea0 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
2deb0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2dec0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
2ded0 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
2dee0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2def0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2df00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2df10 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2df20 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2df30 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2df40 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
2df50 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2df60 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
2df70 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
2df80 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
2df90 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
2dfa0 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
2dfb0 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
2dfc0 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
2dfd0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
2dfe0 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
2dff0 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
2e000 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
2e010 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73  inter references
2e020 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
2e030 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
2e040 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
2e050 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
2e060 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
2e070 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
2e080 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
2e090 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
2e0a0 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
2e0b0 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
2e0c0 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
2e0d0 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
2e0e0 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
2e0f0 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
2e100 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
2e110 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
2e120 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
2e130 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
2e140 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
2e150 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2e160 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
2e170 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2e180 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e190 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2e1a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2e1b0 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
2e1c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e1d0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
2e1e0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2e1f0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
2e200 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2e210 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2e220 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
2e230 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
2e240 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
2e250 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
2e260 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
2e270 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e280 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
2e290 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2e2a0 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
2e2b0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
2e2c0 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
2e2d0 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
2e2e0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
2e2f0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2e300 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e310 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
2e320 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
2e330 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
2e340 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
2e350 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2e360 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2e370 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2e380 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
2e390 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2e3a0 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
2e3b0 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
2e3c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2e3d0 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
2e3e0 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
2e3f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e400 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
2e410 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2e420 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
2e430 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
2e440 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
2e450 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
2e460 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
2e470 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2e480 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e490 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2e4a0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
2e4b0 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
2e4c0 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
2e4d0 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
2e4e0 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
2e4f0 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
2e500 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f  ly.  Do <b>not</
2e510 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  b> pass the poin
2e520 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
2e530 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2e540 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
2e550 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2e560 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20  ], etc. into.** 
2e570 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2e580 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d  ..**.** ^(If a m
2e590 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2e5a0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
2e5b0 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
2e5c0 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
2e5d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
2e5e0 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
2e5f0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
2e600 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
2e610 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
2e620 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
2e630 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2e640 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
2e650 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
2e660 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
2e670 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2e680 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
2e690 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
2e6a0 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63  E_NOMEM].)^.*/.c
2e6b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2e6c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
2e6d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e6e0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2e6f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e700 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
2e710 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2e720 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e730 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
2e740 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2e750 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
2e760 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
2e770 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e780 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2e790 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
2e7a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e7b0 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
2e7c0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
2e7d0 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
2e7e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2e7f0 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  Col);.const unsi
2e800 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
2e810 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
2e820 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e830 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76  t iCol);.const v
2e840 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2e850 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
2e860 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2e870 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2e880 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
2e890 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2e8a0 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76  iCol);.sqlite3_v
2e8b0 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
2e8c0 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
2e8d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2e8e0 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
2e8f0 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
2e900 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2e910 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
2e920 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
2e930 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
2e940 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
2e950 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
2e960 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2e970 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2e980 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
2e990 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2e9a0 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65  encountered no e
2e9b0 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74  rrors.** or if t
2e9c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2e9d0 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75  never been evalu
2e9e0 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ated, then sqlit
2e9f0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65  e3_finalize() re
2ea00 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f  turns.** SQLITE_
2ea10 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73  OK.  ^If the mos
2ea20 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
2ea30 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74  ion of statement
2ea40 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a   S failed, then.
2ea50 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ** sqlite3_final
2ea60 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74  ize(S) returns t
2ea70 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  he appropriate [
2ea80 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a  error code] or.*
2ea90 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  * [extended erro
2eaa0 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
2eab0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
2eac0 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20  lize(S) routine 
2ead0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
2eae0 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
2eaf0 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79  g.** the life cy
2eb00 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64  cle of [prepared
2eb10 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a   statement] S:.*
2eb20 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65  * before stateme
2eb30 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61  nt S is ever eva
2eb40 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a  luated, after.**
2eb50 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c   one or more cal
2eb60 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
2eb70 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65  eset()], or afte
2eb80 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f  r any call.** to
2eb90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2eba0 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  ] regardless of 
2ebb0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
2ebc0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
2ebd0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
2ebe0 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ecution..**.** ^
2ebf0 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  Invoking sqlite3
2ec00 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61  _finalize() on a
2ec10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2ec20 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
2ec30 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  p..**.** The app
2ec40 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69  lication must fi
2ec50 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72  nalize every [pr
2ec60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ec70 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76  ] in order to av
2ec80 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20  oid.** resource 
2ec90 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20  leaks.  It is a 
2eca0 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66  grievous error f
2ecb0 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
2ecc0 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65  on to try to use
2ecd0 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73  .** a prepared s
2ece0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
2ecf0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
2ed00 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f  ized.  Any use o
2ed10 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  f a prepared.** 
2ed20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
2ed30 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
2ed40 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74  lized can result
2ed50 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
2ed60 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  d.** undesirable
2ed70 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61   behavior such a
2ed80 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20  s segfaults and 
2ed90 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e  heap corruption.
2eda0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2edb0 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33  finalize(sqlite3
2edc0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2edd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ede0 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64  Reset A Prepared
2edf0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
2ee00 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  t.**.** The sqli
2ee10 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
2ee20 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2ee30 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
2ee40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2ee50 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
2ee60 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
2ee70 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
2ee80 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
2ee90 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65  ^Any SQL stateme
2eea0 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
2eeb0 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
2eec0 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
2eed0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2eee0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
2eef0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
2ef00 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
2ef10 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
2ef20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
2ef30 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
2ef40 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
2ef50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
2ef60 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
2ef70 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
2ef80 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2ef90 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61  atement] S.** ba
2efa0 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
2efb0 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
2efc0 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  am..**.** ^If th
2efd0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2efe0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2eff0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2f000 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2f010 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
2f020 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2f030 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2f040 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69  ,.** or if [sqli
2f050 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
2f060 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
2f070 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
2f080 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** then [sqlite3
2f090 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
2f0a0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
2f0b0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
2f0c0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2f0d0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2f0e0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
2f0f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f100 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
2f110 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
2f120 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2f130 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
2f140 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
2f150 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
2f160 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
2f170 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
2f180 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
2f190 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
2f1a0 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
2f1b0 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
2f1c0 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70  gs] on the [prep
2f1d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f1e0 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  S..*/.int sqlite
2f1f0 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
2f200 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2f210 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2f220 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e  reate Or Redefin
2f230 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a  e SQL Functions.
2f240 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75  ** KEYWORDS: {fu
2f250 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
2f260 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59  routines}.** KEY
2f270 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
2f280 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2f290 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59  function}.** KEY
2f2a0 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
2f2b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2f2c0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
2f2d0 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
2f2e0 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
2f2f0 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69  known as "functi
2f300 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
2f310 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73  ines").** are us
2f320 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
2f330 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
2f340 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65  gates or to rede
2f350 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
2f360 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67  r.** of existing
2f370 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
2f380 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
2f390 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
2f3a0 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ces between.** t
2f3b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2f3c0 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  e the text encod
2f3d0 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72  ing expected for
2f3e0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
2f3f0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61  arameter (the na
2f400 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  me of the functi
2f410 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  on being created
2f420 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65  ).** and the pre
2f430 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65  sence or absence
2f440 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72   of a destructor
2f450 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a   callback for.**
2f460 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2f470 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a   data pointer..*
2f480 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2f490 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2f4a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f4b0 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
2f4c0 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
2f4d0 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
2f4e0 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c  ed.  ^If an appl
2f4f0 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72  ication uses mor
2f500 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
2f510 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2f520 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69  n then applicati
2f530 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2f540 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
2f550 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63   added.** to eac
2f560 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
2f570 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79  ction separately
2f580 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
2f590 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2f5a0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2f5b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
2f5c0 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
2f5d0 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54  * redefined.  ^T
2f5e0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
2f5f0 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
2f600 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e   to 255 bytes in
2f610 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72   a UTF-8.** repr
2f620 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c  esentation, excl
2f630 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
2f640 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  o-terminator.  ^
2f650 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
2f660 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d  me.** length lim
2f670 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62  it is in UTF-8 b
2f680 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63  ytes, not charac
2f690 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20  ters nor UTF-16 
2f6a0 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79  bytes.  .** ^Any
2f6b0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
2f6c0 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
2f6d0 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
2f6e0 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
2f6f0 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  in [SQLITE_MISUS
2f700 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  E] being returne
2f710 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  d..**.** ^The th
2f720 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e  ird parameter (n
2f730 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e  Arg).** is the n
2f740 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2f750 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
2f760 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2f770 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
2f780 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74  ^If this paramet
2f790 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74  er is -1, then t
2f7a0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2f7b0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
2f7c0 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
2f7d0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
2f7e0 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
2f7f0 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20  he limit.** set 
2f800 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
2f810 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
2f820 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e  _FUNCTION_ARG]).
2f830 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a    If the third.*
2f840 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c  * parameter is l
2f850 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67  ess than -1 or g
2f860 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20  reater than 127 
2f870 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2f880 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
2f890 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
2f8a0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
2f8b0 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
2f8c0 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c  ies what.** [SQL
2f8d0 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
2f8e0 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
2f8f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
2f900 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
2f910 61 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72  arameters.  Ever
2f920 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  y SQL function i
2f930 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
2f940 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f  st be able to wo
2f950 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38  rk.** with UTF-8
2f960 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
2f970 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
2f980 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
2f990 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
2f9a0 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
2f9b0 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
2f9c0 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e  an another.  ^An
2f9d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
2f9e0 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
2f9f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2fa00 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
2fa10 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2fa20 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  6() multiple.** 
2fa30 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
2fa40 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74  ame function but
2fa50 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
2fa60 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52  values of eTextR
2fa70 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c  ep..** ^When mul
2fa80 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
2fa90 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2faa0 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61  e function are a
2fab0 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65  vailable, SQLite
2fac0 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68  .** will pick th
2fad0 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c  e one that invol
2fae0 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  ves the least am
2faf0 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e  ount of data con
2fb00 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74  version..** If t
2fb10 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73  here is only a s
2fb20 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ingle implementa
2fb30 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20  tion which does 
2fb40 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65  not care what te
2fb50 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69  xt.** encoding i
2fb60 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  s used, then the
2fb70 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2fb80 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49   should be [SQLI
2fb90 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  TE_ANY]..**.** ^
2fba0 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
2fbb0 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
2fbc0 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
2fbd0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2fbe0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
2fbf0 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
2fc00 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
2fc10 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
2fc20 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
2fc30 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
2fc40 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e  ixth, seventh an
2fc50 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74  d eighth paramet
2fc60 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
2fc70 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
2fc80 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
2fc90 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
2fca0 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
2fcb0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
2fcc0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2fcd0 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
2fce0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
2fcf0 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
2fd00 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
2fd10 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
2fd20 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
2fd30 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61  nters must be pa
2fd40 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
2fd50 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
2fd60 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
2fd70 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2fd80 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
2fd90 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
2fda0 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
2fdb0 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
2fdc0 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62  L pointer must b
2fdd0 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
2fde0 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
2fdf0 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
2fe00 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
2fe10 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
2fe20 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20  LL pointers for 
2fe30 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
2fe40 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e  on.** callbacks.
2fe50 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
2fe60 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  ninth parameter 
2fe70 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
2fe80 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
2fe90 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
2fea0 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72  then it is destr
2feb0 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70  uctor for the ap
2fec0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
2fed0 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20  ointer. .** The 
2fee0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e  destructor is in
2fef0 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66  voked when the f
2ff00 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
2ff10 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65  ed, either by be
2ff20 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65  ing.** overloade
2ff30 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61  d or when the da
2ff40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ff50 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e  n closes.)^.** ^
2ff60 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2ff70 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69  s also invoked i
2ff80 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  f the call to.**
2ff90 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2ffa0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61  function_v2() fa
2ffb0 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ils..** ^When th
2ffc0 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  e destructor cal
2ffd0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e  lback of the ten
2ffe0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2fff0 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69  invoked, it.** i
30000 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c  s passed a singl
30010 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
30020 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
30030 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
30040 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77  ta .** pointer w
30050 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66  hich was the fif
30060 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
30070 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30080 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  unction_v2()..**
30090 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
300a0 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
300b0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
300c0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
300d0 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
300e0 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
300f0 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
30100 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
30110 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
30120 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
30130 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
30140 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
30150 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
30160 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
30170 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
30180 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
30190 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
301a0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
301b0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
301c0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
301d0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
301e0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
301f0 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
30200 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
30210 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
30220 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
30230 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
30240 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66  tive nArg.  ^A f
30250 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
30260 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
30270 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
30280 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
30290 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
302a0 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
302b0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
302c0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
302d0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
302e0 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f    .** ^A functio
302f0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
30300 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
30310 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
30320 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
30330 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
30340 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
30350 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
30360 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
30370 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
30380 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
30390 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20  **.** ^Built-in 
303a0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
303b0 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
303c0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
303d0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
303e0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
303f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30400 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
30410 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
30420 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
30430 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
30440 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
30450 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
30460 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
30470 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
30480 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
30490 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
304a0 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
304b0 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
304c0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e  s running..*/.in
304d0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
304e0 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
304f0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
30500 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
30510 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
30520 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
30530 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
30540 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
30550 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30560 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
30570 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
30580 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
30590 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
305a0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
305b0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
305c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
305d0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
305e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
305f0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
30600 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
30610 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
30620 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
30630 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
30640 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
30650 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
30660 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
30670 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
30680 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
30690 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
306a0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
306b0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
306c0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
306d0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
306e0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
306f0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20  _function_v2(.  
30700 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
30710 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
30720 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
30730 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
30740 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
30750 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
30760 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
30770 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
30780 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
30790 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
307a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
307b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
307c0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
307d0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
307e0 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  xt*),.  void(*xD
307f0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
30800 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30810 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
30820 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
30830 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
30840 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
30850 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
30860 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
30870 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
30880 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
30890 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
308a0 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
308b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
308c0 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
308d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
308e0 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
308f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
30900 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
30910 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
30920 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
30930 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
30940 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
30950 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
30960 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e  eate_function on
30970 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
30980 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
30990 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
309a0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
309b0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
309c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
309d0 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
309e0 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
309f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
30a00 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
30a10 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
30a20 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
30a30 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
30a40 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
30a50 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
30a60 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
30a70 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
30a80 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
30a90 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
30aa0 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
30ab0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
30ac0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
30ad0 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
30ae0 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
30af0 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
30b00 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
30b10 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
30b20 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74   tell you what t
30b30 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
30b40 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
30b50 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
30b60 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
30b70 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
30b80 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  e_count(sqlite3_
30b90 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
30ba0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
30bb0 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
30bc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
30bd0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
30be0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  ED int sqlite3_t
30bf0 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
30c00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30c10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
30c20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
30c30 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  D int sqlite3_gl
30c40 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
30c50 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
30c60 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
30c70 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
30c80 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  p(void);.SQLITE_
30c90 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
30ca0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
30cb0 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64  arm(void(*)(void
30cc0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  *,sqlite3_int64,
30cd0 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20  int),.          
30ce0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
30cf0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
30d00 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
30d10 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
30d20 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
30d30 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
30d40 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  s.**.** The C-la
30d50 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
30d60 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
30d70 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
30d80 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
30d90 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
30da0 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
30db0 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
30dc0 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
30dd0 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
30de0 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a  r aggregate..**.
30df0 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
30e00 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
30e10 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
30e20 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
30e30 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
30e40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30e50 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
30e60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30e70 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
30e80 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
30e90 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
30ea0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
30eb0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
30ec0 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72  ..** The 3rd par
30ed0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
30ee0 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
30ef0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
30f00 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
30f10 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30f20 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
30f30 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
30f40 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
30f50 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
30f60 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
30f70 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
30f80 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
30f90 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
30fa0 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
30fb0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
30fc0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
30fd0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
30fe0 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
30ff0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
31000 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
31010 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
31020 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
31030 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
31040 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
31050 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
31060 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
31070 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
31080 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
31090 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
310a0 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
310b0 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
310c0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
310d0 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
310e0 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
310f0 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
31100 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
31110 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
31120 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
31130 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
31140 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
31150 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
31160 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
31170 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31180 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
31190 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
311a0 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
311b0 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
311c0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
311d0 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
311e0 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
311f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31200 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
31210 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
31220 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
31230 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
31240 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
31250 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
31260 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
31270 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
31280 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
31290 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
312a0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
312b0 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
312c0 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
312d0 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
312e0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
312f0 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
31300 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
31310 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
31320 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
31330 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
31340 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
31350 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
31360 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
31370 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
31380 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
31390 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
313a0 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
313b0 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
313c0 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
313d0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
313e0 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
313f0 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
31400 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
31410 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
31420 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
31430 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
31440 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
31450 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
31460 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
31470 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
31480 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
31490 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
314a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
314b0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
314c0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
314d0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
314e0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
314f0 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
31500 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
31510 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
31520 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
31530 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
31540 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
31550 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
31560 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
31570 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
31580 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
31590 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
315a0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
315b0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
315c0 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
315d0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
315e0 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
315f0 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
31600 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
31610 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
31620 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
31630 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
31640 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
31650 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
31660 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
31670 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
31680 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
31690 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
316a0 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
316b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
316c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
316d0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
316e0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
316f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
31700 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
31710 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
31720 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
31730 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
31740 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
31750 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31760 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
31770 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31780 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
31790 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
317a0 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
317b0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
317c0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
317d0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
317e0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
317f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
31800 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31810 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
31820 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
31830 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31840 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31850 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
31860 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
31870 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
31880 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67  entations of agg
31890 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
318a0 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
318b0 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
318c0 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
318d0 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
318e0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
318f0 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
31900 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31910 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
31920 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
31930 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
31940 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
31950 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
31960 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
31970 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
31980 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
31990 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
319a0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
319b0 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
319c0 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
319d0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
319e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
319f0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
31a00 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
31a10 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
31a20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
31a30 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
31a40 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
31a50 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31a60 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
31a70 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
31a80 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
31a90 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
31aa0 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
31ab0 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
31ac0 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
31ad0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
31ae0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
31af0 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
31b00 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
31b10 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
31b20 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
31b30 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
31b40 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
31b50 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
31b60 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
31b70 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
31b80 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
31b90 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
31ba0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
31bb0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
31bc0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
31bd0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
31be0 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
31bf0 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
31c00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
31c10 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31c20 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
31c30 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
31c40 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72  ter .** when fir
31c50 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69  st called if N i
31c60 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  s less than or e
31c70 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
31c80 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  if a memory.** a
31c90 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
31ca0 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
31cb0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
31cc0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
31cd0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31ce0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
31cf0 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
31d00 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
31d10 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
31d20 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
31d30 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
31d40 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
31d50 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
31d60 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
31d70 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
31d80 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
31d90 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
31da0 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
31db0 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
31dc0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
31dd0 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65  n.)^  Within the
31de0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
31df0 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72  , it is customar
31e00 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20  y to set.** N=0 
31e10 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  in calls to sqli
31e20 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
31e30 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68  ntext(C,N) so th
31e40 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c  at no .** pointl
31e50 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ess memory alloc
31e60 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a  ations occur..**
31e70 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
31e80 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
31e90 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
31ea0 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
31eb0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
31ec0 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
31ed0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
31ee0 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
31ef0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
31f00 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
31f10 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
31f20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
31f30 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
31f40 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
31f50 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
31f60 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
31f70 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
31f80 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
31f90 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
31fa0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
31fb0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
31fc0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
31fd0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
31fe0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
31ff0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
32000 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
32010 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
32020 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
32030 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
32040 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
32050 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
32060 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
32070 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
32080 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
32090 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
320a0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
320b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
320c0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
320d0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
320e0 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
320f0 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
32100 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
32110 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
32120 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32130 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
32140 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32150 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
32160 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
32170 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
32180 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
32190 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
321a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
321b0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
321c0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
321d0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
321e0 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
321f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32200 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
32210 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
32220 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
32230 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
32240 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32250 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
32260 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
32270 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
32280 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
32290 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
322a0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
322b0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
322c0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
322d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
322e0 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
322f0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
32300 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32310 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
32320 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
32330 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
32340 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
32350 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
32360 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
32370 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
32380 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c  function..*/.sql
32390 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
323a0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
323b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
323c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
323d0 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
323e0 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
323f0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
32400 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
32410 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29   (non-aggregate)
32420 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
32430 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
32440 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
32450 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
32460 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
32470 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
32480 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
32490 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
324a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
324b0 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
324c0 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
324d0 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
324e0 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
324f0 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
32500 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20   preserved.  An 
32510 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68  example.** of wh
32520 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62  ere this might b
32530 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61  e useful is in a
32540 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
32550 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20  ion matching.** 
32560 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
32570 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
32580 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
32590 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
325a0 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
325b0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
325c0 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72   with the patter
325d0 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54  n string.  .** T
325e0 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  hen as long as t
325f0 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
32600 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61  g remains the sa
32610 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69  me,.** the compi
32620 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
32630 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
32640 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
32650 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
32660 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
32670 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
32680 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
32690 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
326a0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
326b0 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
326c0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
326d0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
326e0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
326f0 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
32700 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
32710 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
32720 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32730 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74   function. ^If t
32740 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64  here is no metad
32750 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
32760 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74  d with the funct
32770 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68  ion argument, th
32780 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  is sqlite3_get_a
32790 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
327a0 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ce.** returns a 
327b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
327c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
327d0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
327e0 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20  ,P,X) interface 
327f0 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64  saves P as metad
32800 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
32810 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
32820 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
32830 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
32840 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a  .  ^Subsequent.*
32850 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
32860 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43  e3_get_auxdata(C
32870 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f  ,N) return P fro
32880 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  m the most recen
32890 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  t.** sqlite3_set
328a0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
328b0 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65  ) call if the me
328c0 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20  tadata is still 
328d0 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c  valid or.** NULL
328e0 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61   if the metadata
328f0 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72   has been discar
32900 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65  ded..** ^After e
32910 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
32920 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
32930 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58  C,N,P,X) where X
32940 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
32950 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
32960 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
32970 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69  or function X wi
32980 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65  th parameter P e
32990 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20  xactly.** once, 
329a0 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74  when the metadat
329b0 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a  a is discarded..
329c0 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
329d0 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65  e to discard the
329e0 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79   metadata at any
329f0 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67   time, including
32a00 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77  : <ul>.** <li> w
32a10 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
32a20 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
32a30 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
32a40 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  , or.** <li> whe
32a50 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
32a60 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
32a70 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
32a80 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
32a90 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
32aa0 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ent, or.** <li> 
32ab0 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74  when sqlite3_set
32ac0 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e  _auxdata() is in
32ad0 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  voked again on t
32ae0 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65  he same paramete
32af0 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75  r, or.** <li> du
32b00 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61  ring the origina
32b10 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  l sqlite3_set_au
32b20 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65  xdata() call whe
32b30 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20  n a memory .**  
32b40 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65      allocation e
32b50 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75  rror occurs. </u
32b60 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  l>)^.**.** Note 
32b70 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20  the last bullet 
32b80 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20  in particular.  
32b90 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58  The destructor X
32ba0 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   in .** sqlite3_
32bb0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
32bc0 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61  P,X) might be ca
32bd0 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  lled immediately
32be0 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20  , before the.** 
32bf0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32c00 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
32c10 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48  even returns.  H
32c20 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ence sqlite3_set
32c30 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68  _auxdata().** sh
32c40 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e  ould be called n
32c50 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ear the end of t
32c60 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
32c70 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74  ementation and t
32c80 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  he.** function i
32c90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
32ca0 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e  ould not make an
32cb0 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65 72  y use of P after
32cc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
32cd0 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62 65  auxdata() has be
32ce0 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a  en called..**.**
32cf0 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
32d00 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
32d10 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
32d20 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
32d30 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
32d40 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
32d50 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f   compile-time co
32d60 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69  nstants, includi
32d70 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  ng literal.** va
32d80 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
32d90 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73  ters] and expres
32da0 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66  sions composed f
32db0 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a  rom the same.)^.
32dc0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
32dd0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
32de0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
32df0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
32e00 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
32e10 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
32e20 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
32e30 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
32e40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32e50 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
32e60 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
32e70 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
32e80 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
32e90 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
32ea0 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
32eb0 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
32ec0 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
32ed0 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
32ee0 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  vior.**.** These
32ef0 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
32f00 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74  ues for the dest
32f10 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
32f20 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
32f30 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
32f40 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
32f50 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
32f60 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66  lt_blob()].  ^If
32f70 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
32f80 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53  ** argument is S
32f90 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74  QLITE_STATIC, it
32fa0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
32fb0 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20  content pointer 
32fc0 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61  is constant.** a
32fd0 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68  nd will never ch
32fe0 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e  ange.  It does n
32ff0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65  ot need to be de
33000 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a  stroyed.  ^The.*
33010 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
33020 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
33030 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
33040 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
33050 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
33060 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
33070 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
33080 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
33090 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
330a0 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
330b0 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
330c0 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
330d0 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
330e0 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
330f0 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
33100 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
33110 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
33120 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
33130 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
33140 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
33150 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
33160 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
33170 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
33180 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
33190 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
331a0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
331b0 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
331c0 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
331d0 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
331e0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a  SQL Function.**.
331f0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
33200 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
33210 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
33220 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
33230 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
33240 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
33250 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
33260 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
33270 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
33280 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
33290 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
332a0 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
332b0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
332c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
332d0 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
332e0 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
332f0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
33300 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
33310 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
33320 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
33330 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
33340 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
33350 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
33360 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
33370 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
33380 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
33390 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
333a0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
333b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
333c0 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
333d0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
333e0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
333f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33400 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
33410 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
33420 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
33430 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
33440 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
33450 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
33460 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
33470 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
33480 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
33490 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
334a0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
334b0 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
334c0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
334d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
334e0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
334f0 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74  o be a BLOB cont
33500 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a  aining all zero.
33510 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62  ** bytes and N b
33520 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68  ytes in size, wh
33530 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c  ere N is the val
33540 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61  ue of the 2nd pa
33550 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
33560 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33570 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
33580 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
33590 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
335a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
335b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
335c0 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
335d0 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
335e0 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
335f0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
33600 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33610 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
33620 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
33630 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
33640 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
33650 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
33660 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
33670 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
33680 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  n..** ^SQLite us
33690 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
336a0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
336b0 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
336c0 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
336d0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
336e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
336f0 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
33700 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
33710 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c  r message.  ^SQL
33720 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
33730 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
33740 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
33750 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33760 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e  rror() as UTF-8.
33770 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65   ^SQLite.** inte
33780 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
33790 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
337a0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
337b0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
337c0 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
337d0 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72  r.  ^If the thir
337e0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
337f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33800 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
33810 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33820 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  16() is negative
33830 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
33840 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a  es as the error.
33850 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74  ** message all t
33860 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74  ext up through t
33870 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
33880 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
33890 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
338a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
338b0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
338c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
338d0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
338e0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
338f0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
33900 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
33910 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
33920 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
33930 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
33940 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
33950 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33960 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
33970 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
33980 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
33990 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
339a0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
339b0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
339c0 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
339d0 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
339e0 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
339f0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
33a00 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
33a10 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
33a20 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
33a30 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
33a40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33a50 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
33a60 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
33a70 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
33a80 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
33a90 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
33aa0 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
33ab0 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
33ac0 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a   ^By default,.**
33ad0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
33ae0 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  is SQLITE_ERROR.
33af0 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20    ^A subsequent 
33b00 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
33b10 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
33b20 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
33b30 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65  ult_error16() re
33b40 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63  sets the error c
33b50 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52  ode to SQLITE_ER
33b60 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ROR..**.** ^The 
33b70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33b80 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e  rror_toobig() in
33b90 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
33ba0 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
33bb0 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
33bc0 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
33bd0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
33be0 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
33bf0 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
33c00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33c10 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e  error_nomem() in
33c20 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
33c30 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
33c40 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
33c50 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d  ating that a mem
33c60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
33c70 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ailed..**.** ^Th
33c80 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33c90 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
33ca0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
33cb0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
33cc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33cd0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
33ce0 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
33cf0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
33d00 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
33d10 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
33d20 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
33d30 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29  3_result_int64()
33d40 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
33d50 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
33d60 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
33d70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
33d80 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
33d90 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  e 64-bit signed 
33da0 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
33db0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
33dc0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
33dd0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33de0 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
33df0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
33e00 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
33e10 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
33e20 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33e30 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
33e40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33e50 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
33e60 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
33e70 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
33e80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33e90 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
33ea0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33eb0 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
33ec0 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
33ed0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
33ee0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33ef0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
33f00 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
33f10 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
33f20 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
33f30 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
33f40 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
33f50 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
33f60 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
33f70 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
33f80 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53  pectively..** ^S
33f90 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20  QLite takes the 
33fa0 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d  text result from
33fb0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33fc0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64   from.** the 2nd
33fd0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
33fe0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33ff0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
34000 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  s..** ^If the 3r
34010 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
34020 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34030 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
34040 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  es.** is negativ
34050 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  e, then SQLite t
34060 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74  akes result text
34070 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
34080 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75  rameter.** throu
34090 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
340a0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
340b0 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
340c0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
340d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
340e0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
340f0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
34100 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79   then as many by
34110 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
34120 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74  ers) of the text
34130 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
34140 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
34150 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73  ter are taken as
34160 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34170 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63  -defined.** func
34180 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66  tion result.  If
34190 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
341a0 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  er is non-negati
341b0 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d  ve, then it.** m
341c0 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
341d0 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20  offset into the 
341e0 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65  string where the
341f0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
34200 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20  would.** appear 
34210 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68  if the string wh
34220 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  ere NUL terminat
34230 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
34240 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
34250 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e  .** in the strin
34260 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73  g at a byte offs
34270 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  et that is less 
34280 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f  than the value o
34290 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72  f the 3rd.** par
342a0 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ameter, then the
342b0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
342c0 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65  g will contain e
342d0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64  mbedded NULs and
342e0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f   the.** result o
342f0 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70  f expressions op
34300 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e  erating on strin
34310 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  gs with embedded
34320 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
34330 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  ed..** ^If the 4
34340 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
34350 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
34360 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
34370 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
34380 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
34390 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
343a0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
343b0 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66   calls that.** f
343c0 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64  unction as the d
343d0 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
343e0 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
343f0 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73  sult when it has
34400 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69  .** finished usi
34410 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
34420 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
34430 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
34440 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34450 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ext* interfaces 
34460 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  or to.** sqlite3
34470 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
34480 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
34490 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54  tant SQLITE_STAT
344a0 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a  IC, then SQLite.
344b0 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ** assumes that 
344c0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
344d0 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f   result is in co
344e0 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64  nstant space and
344f0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70   does not.** cop
34500 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  y the content of
34510 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e   the parameter n
34520 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75  or call a destru
34530 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74  ctor on the cont
34540 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68  ent.** when it h
34550 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
34560 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
34570 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
34580 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
34590 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
345a0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
345b0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
345c0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
345d0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
345e0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
345f0 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65  T.** then SQLite
34600 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
34610 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f   the result into
34620 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20   space obtained 
34630 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  from.** from [sq
34640 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
34650 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
34660 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
34670 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
34680 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
34690 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
346a0 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
346b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
346c0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
346d0 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f  py the.** [unpro
346e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
346f0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65  alue] object spe
34700 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e  cified by the 2n
34710 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54  d parameter.  ^T
34720 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  he.** sqlite3_re
34730 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
34740 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
34750 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
34760 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f  te3_value].** so
34770 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
34780 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66  e3_value] specif
34790 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d  ied in the param
347a0 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20  eter may change 
347b0 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63  or.** be dealloc
347c0 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ated after sqlit
347d0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
347e0 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75  ) returns withou
347f0 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70  t harm..** ^A [p
34800 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
34810 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d  _value] object m
34820 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65  ay always be use
34830 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75  d where an.** [u
34840 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
34850 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
34860 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f   is required, so
34870 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20   either.** kind 
34880 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
34890 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65  e] object can be
348a0 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20   used with this 
348b0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
348c0 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   If these routin
348d0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  es are called fr
348e0 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69  om within the di
348f0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a  fferent thread.*
34900 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63  * than the one c
34910 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70  ontaining the ap
34920 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34930 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  d function that 
34940 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20  received.** the 
34950 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
34960 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72  ] pointer, the r
34970 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
34980 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ined..*/.void sq
34990 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
349a0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
349b0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
349c0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
349d0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
349e0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
349f0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
34a00 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
34a10 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34a20 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
34a30 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
34a40 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
34a50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34a60 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
34a70 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
34a80 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
34a90 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34aa0 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
34ab0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
34ac0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
34ad0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
34ae0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34af0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
34b00 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
34b10 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  de(sqlite3_conte
34b20 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
34b30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
34b40 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
34b50 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
34b60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
34b70 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
34b80 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
34b90 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
34ba0 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
34bb0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34bc0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34bd0 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69  result_text(sqli
34be0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
34bf0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20  nst char*, int, 
34c00 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
34c10 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
34c20 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
34c30 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
34c40 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
34c50 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
34c60 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
34c70 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
34c80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34c90 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
34ca0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
34cb0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
34cc0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
34cd0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34ce0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
34cf0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
34d00 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34d10 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
34d20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
34d30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34d40 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34d50 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
34d60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
34d70 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
34d80 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
34d90 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
34da0 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  uences.**.** ^Th
34db0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64  ese functions ad
34dc0 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f  d, remove, or mo
34dd0 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f  dify a [collatio
34de0 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  n] associated.**
34df0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
34e00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
34e10 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
34e20 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
34e30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
34e40 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
34e50 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  n is a UTF-8 str
34e60 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
34e70 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34e80 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
34e90 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34ea0 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
34eb0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
34ec0 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
34ed0 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
34ee0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34ef0 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  16()..** ^Collat
34f00 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63  ion names that c
34f10 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63  ompare equal acc
34f20 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74  ording to [sqlit
34f30 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61  e3_strnicmp()] a
34f40 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
34f50 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20   to be the same 
34f60 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  name..**.** ^(Th
34f70 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
34f80 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74   (eTextRep) must
34f90 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
34fa0 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c  onstants:.** <ul
34fb0 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
34fc0 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e  E_UTF8],.** <li>
34fd0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
34fe0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
34ff0 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
35000 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
35010 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  16], or.** <li> 
35020 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
35030 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  IGNED]..** </ul>
35040 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74  )^.** ^The eText
35050 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74  Rep argument det
35060 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f  ermines the enco
35070 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20  ding of strings 
35080 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65  passed.** to the
35090 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
350a0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43  ion callback, xC
350b0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
350c0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
350d0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  and [SQLITE_UTF1
350e0 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
350f0 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a  s for eTextRep.*
35100 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20  * force strings 
35110 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68  to be UTF16 with
35120 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
35130 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  er..** ^The [SQL
35140 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
35150 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65  D] value for eTe
35160 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72  xtRep forces str
35170 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a  ings to begin.**
35180 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65   on an even byte
35190 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20   address..**.** 
351a0 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75  ^The fourth argu
351b0 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61  ment, pArg, is a
351c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  n application da
351d0 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ta pointer that 
351e0 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72  is passed.** thr
351f0 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
35200 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
35210 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
35220 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  tion callback..*
35230 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
35240 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62  argument, xCallb
35250 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65  ack, is a pointe
35260 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  r to the collati
35270 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ng function..** 
35280 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74  ^Multiple collat
35290 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61  ing functions ca
352a0 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
352b0 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  using the same n
352c0 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20  ame but.** with 
352d0 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
352e0 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e  ep parameters an
352f0 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  d SQLite will us
35300 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66  e whichever.** f
35310 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
35320 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
35330 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66  t of data transf
35340 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  ormation..** ^If
35350 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61   the xCallback a
35360 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20  rgument is NULL 
35370 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  then the collati
35380 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  ng function is.*
35390 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65  * deleted.  ^Whe
353a0 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20  n all collating 
353b0 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67  functions having
353c0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61   the same name a
353d0 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74  re deleted,.** t
353e0 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  hat collation is
353f0 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c   no longer usabl
35400 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f  e..**.** ^The co
35410 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35420 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
35430 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79  oked with a copy
35440 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a   of the pArg .**
35450 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
35460 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69  a pointer and wi
35470 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69  th two strings i
35480 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  n the encoding s
35490 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
354a0 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
354b0 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61  ment.  The colla
354c0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
354d0 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20  st return an.** 
354e0 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20  integer that is 
354f0 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20  negative, zero, 
35500 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69  or positive.** i
35510 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
35520 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
35530 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
35540 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
35550 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63  econd,.** respec
35560 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61  tively.  A colla
35570 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
35580 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  st always return
35590 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72   the same answer
355a0 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61  .** given the sa
355b0 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74  me inputs.  If t
355c0 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61  wo or more colla
355d0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
355e0 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a  re registered.**
355f0 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   to the same col
35600 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69  lation name (usi
35610 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  ng different eTe
35620 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68  xtRep values) th
35630 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67  en all.** must g
35640 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e  ive an equivalen
35650 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e  t answer when in
35660 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76  voked with equiv
35670 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a  alent strings..*
35680 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * The collating 
35690 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62  function must ob
356a0 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ey the following
356b0 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20   properties for 
356c0 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41  all.** strings A
356d0 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a  , B, and C:.**.*
356e0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49  * <ol>.** <li> I
356f0 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41  f A==B then B==A
35700 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  ..** <li> If A==
35710 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20  B and B==C then 
35720 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  A==C..** <li> If
35730 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67   A&lt;B THEN B&g
35740 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  t;A..** <li> If 
35750 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b  A&lt;B and B&lt;
35760 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a  C then A&lt;C..*
35770 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </ol>.**.** If
35780 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   a collating fun
35790 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20  ction fails any 
357a0 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e  of the above con
357b0 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61  straints and tha
357c0 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66  t.** collating f
357d0 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69  unction is  regi
357e0 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c  stered and used,
357f0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
35800 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
35810 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
35820 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35830 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35840 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
35850 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
35860 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
35870 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f  with the additio
35880 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74  n that the xDest
35890 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
358a0 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20  invoked on pArg 
358b0 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c  when.** the coll
358c0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
358d0 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43  s deleted..** ^C
358e0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
358f0 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77  ns are deleted w
35900 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
35910 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
35920 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  .** calls to the
35930 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
35940 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
35950 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61   when the.** [da
35960 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35970 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69  n] is closed usi
35980 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
35990 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  e()]..**.** ^The
359a0 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
359b0 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e  ck is <u>not</u>
359c0 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a   called if the .
359d0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
359e0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
359f0 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e   function fails.
35a00 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
35a10 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  hat invoke.** sq
35a20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
35a30 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68  lation_v2() with
35a40 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73   a non-NULL xDes
35a50 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68  troy argument sh
35a60 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74  ould .** check t
35a70 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61  he return code a
35a80 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  nd dispose of th
35a90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
35aa0 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  ta pointer.** th
35ab0 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20  emselves rather 
35ac0 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53  than expecting S
35ad0 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69  QLite to deal wi
35ae0 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a  th it for them..
35af0 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65  ** This is diffe
35b00 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20  rent from every 
35b10 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
35b20 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63  erface.  The inc
35b30 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69  onsistency .** i
35b40 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75  s unfortunate bu
35b50 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  t cannot be chan
35b60 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  ged without brea
35b70 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a  king backwards .
35b80 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
35b90 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
35ba0 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
35bb0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
35bc0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
35bd0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
35be0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
35bf0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
35c00 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
35c10 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
35c20 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
35c30 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
35c40 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
35c50 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
35c60 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
35c70 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
35c80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
35c90 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
35ca0 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
35cb0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
35cc0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
35cd0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
35ce0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
35cf0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
35d00 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
35d10 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
35d20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
35d30 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
35d40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
35d50 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  lation16(.  sqli
35d60 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76  te3*, .  const v
35d70 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e  oid *zName,.  in
35d80 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
35d90 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
35da0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
35db0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
35dc0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
35dd0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
35de0 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
35df0 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
35e00 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69  s.**.** ^To avoi
35e10 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
35e20 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
35e30 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
35e40 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
35e50 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
35e60 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
35e70 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
35e80 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
35e90 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
35ea0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
35eb0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
35ec0 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
35ed0 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
35ee0 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
35ef0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  red..**.** ^If t
35f00 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
35f10 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
35f20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
35f30 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
35f40 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
35f50 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
35f60 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
35f70 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
35f80 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
35f90 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
35fa0 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  -8. ^If sqlite3_
35fb0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
35fc0 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
35fd0 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
35fe0 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
35ff0 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
36000 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
36010 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68   ^A call to eith
36020 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
36030 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e  aces the existin
36040 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64  g collation-need
36050 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ed callback..**.
36060 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61  ** ^(When the ca
36070 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
36080 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
36090 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
360a0 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
360b0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
360c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
360d0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
360e0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
360f0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
36100 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
36110 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
36120 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
36130 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
36140 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
36150 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
36160 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
36170 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
36180 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
36190 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
361a0 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
361b0 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
361c0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
361d0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
361e0 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
361f0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
36200 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
36210 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
36220 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a  sequence.)^.**.*
36230 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
36240 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
36250 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
36260 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
36270 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
36280 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36290 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
362a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
362b0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
362c0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
362d0 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69  tion_v2()]..*/.i
362e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
362f0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73  tion_needed(.  s
36300 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
36310 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
36320 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
36330 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
36340 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  char*).);.int sq
36350 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
36360 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
36370 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
36380 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
36390 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
363a0 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
363b0 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51  *).);..#ifdef SQ
363c0 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f  LITE_HAS_CODEC./
363d0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
363e0 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
363f0 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
36400 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
36410 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
36420 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
36430 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
36440 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
36450 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
36460 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
36470 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
36480 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
36490 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
364a0 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
364b0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
364c0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
364d0 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
364e0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
364f0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
36500 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
36510 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20  e key */.);.int 
36520 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a  sqlite3_key_v2(.
36530 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
36540 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36550 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
36560 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
36570 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
36580 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f  ame,           /
36590 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  * Name of the da
365a0 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
365b0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
365c0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
365d0 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
365e0 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
365f0 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
36600 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
36610 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
36620 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
36630 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
36640 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
36650 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
36660 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
36670 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
36680 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
36690 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
366a0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
366b0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
366c0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
366d0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
366e0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
366f0 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
36700 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
36710 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
36720 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
36730 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
36740 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
36750 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
36760 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74  ew key */.);.int
36770 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76   sqlite3_rekey_v
36780 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
36790 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
367a0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
367b0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
367c0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
367d0 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  DbName,         
367e0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
367f0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
36800 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
36810 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
36820 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
36830 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
36840 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
36850 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64   key for a SEE d
36860 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
36870 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
36880 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20  none of the SEE 
36890 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
368a0 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
368b0 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65  te3_activate_see
368c0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
368d0 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
368e0 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
368f0 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
36900 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c  ndif..#ifdef SQL
36910 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44  ITE_ENABLE_CEROD
36920 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
36930 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
36940 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61  y for a CEROD da
36950 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
36960 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
36970 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44  one of the CEROD
36980 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
36990 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ork..*/.void sql
369a0 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65  ite3_activate_ce
369b0 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  rod(.  const cha
369c0 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
369d0 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
369e0 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
369f0 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
36a00 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64  API3REF: Suspend
36a10 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41   Execution For A
36a20 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a   Short Time.**.*
36a30 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c  * The sqlite3_sl
36a40 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
36a50 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
36a60 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
36a70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
36a80 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
36a90 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
36aa0 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
36ab0 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
36ac0 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
36ad0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
36ae0 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
36af0 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
36b00 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65   with.** millise
36b10 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
36b20 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
36b30 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
36b40 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65  ded up to.** the
36b50 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
36b60 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
36b70 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
36b80 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
36b90 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
36ba0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
36bb0 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
36bc0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
36bd0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
36be0 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
36bf0 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
36c00 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
36c10 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
36c20 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
36c30 20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28    If the xSleep(
36c40 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  ) method.** of t
36c50 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69  he default VFS i
36c60 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
36c70 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20  d correctly, or 
36c80 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
36c90 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20  at.** all, then 
36ca0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
36cb0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
36cc0 6d 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d  may deviate from
36cd0 20 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e   the description
36ce0 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69  .** in the previ
36cf0 6f 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a  ous paragraphs..
36d00 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
36d10 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  leep(int);../*.*
36d20 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
36d30 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
36d40 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
36d50 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49   Files.**.** ^(I
36d60 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61  f this global va
36d70 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74  riable is made t
36d80 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  o point to a str
36d90 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20  ing which is.** 
36da0 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f  the name of a fo
36db0 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72  lder (a.k.a. dir
36dc0 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
36dd0 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  l temporary file
36de0 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
36df0 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e  SQLite when usin
36e00 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71  g a built-in [sq
36e10 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d  lite3_vfs | VFS]
36e20 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  .** will be plac
36e30 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
36e40 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69  tory.)^  ^If thi
36e50 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73  s variable.** is
36e60 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
36e70 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72   then SQLite per
36e80 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66  forms a search f
36e90 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
36ea0 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
36eb0 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
36ec0 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
36ed0 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
36ee0 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
36ef0 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e  ble in more than
36f00 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61   one.** thread a
36f10 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73  t a time.  It is
36f20 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
36f30 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
36f40 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20   variable.** if 
36f50 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
36f60 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
36f70 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d   used at the sam
36f80 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61  e time in a sepa
36f90 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a  rate.** thread..
36fa0 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  ** It is intende
36fb0 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
36fc0 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
36fd0 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
36fe0 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
36ff0 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
37000 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
37010 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
37020 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
37030 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ed and that this
37040 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e   variable remain
37050 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68   unchanged.** th
37060 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  ereafter..**.** 
37070 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65  ^The [temp_store
37080 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
37090 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
370a0 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
370b0 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
370c0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
370d0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
370e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
370f0 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a  ^Furthermore,.**
37100 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
37110 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
37120 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65  a] always assume
37130 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e  s that any strin
37140 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76  g.** that this v
37150 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74  ariable points t
37160 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d  o is held in mem
37170 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
37180 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
37190 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70  alloc] and the p
371a0 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70  ragma may attemp
371b0 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d  t to free that m
371c0 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b  emory.** using [
371d0 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a  sqlite3_free]..*
371e0 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73  * Hence, if this
371f0 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64   variable is mod
37200 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20  ified directly, 
37210 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64  either it should
37220 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c   be.** made NULL
37230 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   or made to poin
37240 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
37250 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
37260 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72  e3_malloc].** or
37270 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66   else the use of
37280 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
37290 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
372a0 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  a] should be avo
372b0 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ided..**.** <b>N
372c0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
372d0 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
372e0 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
372f0 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
37300 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
37310 74 6f 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  to calling [sqli
37320 74 65 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73 71  te3_open] or [sq
37330 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20  lite3_open_v2]. 
37340 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
37350 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
37360 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
37370 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
37380 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
37390 2e 20 20 48 65 72 65 20 69 73 20 61 6e 0a 2a 2a  .  Here is an.**
373a0 20 65 78 61 6d 70 6c 65 20 6f 66 20 68 6f 77 20   example of how 
373b0 74 6f 20 64 6f 20 74 68 69 73 20 75 73 69 6e 67  to do this using
373c0 20 43 2b 2b 20 77 69 74 68 20 74 68 65 20 57 69   C++ with the Wi
373d0 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 3a 0a 2a  ndows Runtime:.*
373e0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
373f0 3e 3c 70 72 65 3e 0a 2a 2a 20 4c 50 43 57 53 54  ><pre>.** LPCWST
37400 52 20 7a 50 61 74 68 20 3d 20 57 69 6e 64 6f 77  R zPath = Window
37410 73 3a 3a 53 74 6f 72 61 67 65 3a 3a 41 70 70 6c  s::Storage::Appl
37420 69 63 61 74 69 6f 6e 44 61 74 61 3a 3a 43 75 72  icationData::Cur
37430 72 65 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b  rent->.** &nbsp;
37440 20 20 20 20 20 54 65 6d 70 6f 72 61 72 79 46 6f       TemporaryFo
37450 6c 64 65 72 2d 3e 50 61 74 68 2d 3e 44 61 74 61  lder->Path->Data
37460 28 29 3b 0a 2a 2a 20 63 68 61 72 20 7a 50 61 74  ();.** char zPat
37470 68 42 75 66 26 23 39 31 3b 4d 41 58 5f 50 41 54  hBuf&#91;MAX_PAT
37480 48 20 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d  H + 1&#93;;.** m
37490 65 6d 73 65 74 28 7a 50 61 74 68 42 75 66 2c 20  emset(zPathBuf, 
374a0 30 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42  0, sizeof(zPathB
374b0 75 66 29 29 3b 0a 2a 2a 20 57 69 64 65 43 68 61  uf));.** WideCha
374c0 72 54 6f 4d 75 6c 74 69 42 79 74 65 28 43 50 5f  rToMultiByte(CP_
374d0 55 54 46 38 2c 20 30 2c 20 7a 50 61 74 68 2c 20  UTF8, 0, zPath, 
374e0 2d 31 2c 20 7a 50 61 74 68 42 75 66 2c 20 73 69  -1, zPathBuf, si
374f0 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 2c 0a  zeof(zPathBuf),.
37500 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 4e 55  ** &nbsp;     NU
37510 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71  LL, NULL);.** sq
37520 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
37530 74 6f 72 79 20 3d 20 73 71 6c 69 74 65 33 5f 6d  tory = sqlite3_m
37540 70 72 69 6e 74 66 28 22 25 73 22 2c 20 7a 50 61  printf("%s", zPa
37550 74 68 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65  thBuf);.** </pre
37560 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
37570 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
37580 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
37590 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
375a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
375b0 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
375c0 72 20 48 6f 6c 64 69 6e 67 20 44 61 74 61 62 61  r Holding Databa
375d0 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e  se Files.**.** ^
375e0 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20  (If this global 
375f0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
37600 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
37610 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
37620 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
37630 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
37640 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
37650 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c  all database fil
37660 65 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  es.** specified 
37670 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20  with a relative 
37680 70 61 74 68 6e 61 6d 65 20 61 6e 64 20 63 72 65  pathname and cre
37690 61 74 65 64 20 6f 72 20 61 63 63 65 73 73 65 64  ated or accessed
376a0 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77 68   by.** SQLite wh
376b0 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74  en using a built
376c0 2d 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71 6c  -in windows [sql
376d0 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 20  ite3_vfs | VFS] 
376e0 77 69 6c 6c 20 62 65 20 61 73 73 75 6d 65 64 0a  will be assumed.
376f0 2a 2a 20 74 6f 20 62 65 20 72 65 6c 61 74 69 76  ** to be relativ
37700 65 20 74 6f 20 74 68 61 74 20 64 69 72 65 63 74  e to that direct
37710 6f 72 79 2e 29 5e 20 5e 49 66 20 74 68 69 73 20  ory.)^ ^If this 
37720 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
37730 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 74  LL.** pointer, t
37740 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
37750 65 73 20 74 68 61 74 20 61 6c 6c 20 64 61 74 61  es that all data
37760 62 61 73 65 20 66 69 6c 65 73 20 73 70 65 63 69  base files speci
37770 66 69 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 72  fied.** with a r
37780 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65  elative pathname
37790 20 61 72 65 20 72 65 6c 61 74 69 76 65 20 74 6f   are relative to
377a0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
377b0 65 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74 68  ectory.** for th
377c0 65 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c 79  e process.  Only
377d0 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
377e0 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 20 74 68   makes use of th
377f0 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72  is global.** var
37800 69 61 62 6c 65 3b 20 69 74 20 69 73 20 69 67 6e  iable; it is ign
37810 6f 72 65 64 20 62 79 20 74 68 65 20 75 6e 69 78  ored by the unix
37820 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e   VFS..**.** Chan
37830 67 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 6f  ging the value o
37840 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
37850 77 68 69 6c 65 20 61 20 64 61 74 61 62 61 73 65  while a database
37860 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a 2a   connection is.*
37870 2a 20 6f 70 65 6e 20 63 61 6e 20 72 65 73 75 6c  * open can resul
37880 74 20 69 6e 20 61 20 63 6f 72 72 75 70 74 20 64  t in a corrupt d
37890 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49  atabase..**.** I
378a0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
378b0 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
378c0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
378d0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
378e0 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
378f0 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
37900 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
37910 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
37920 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
37930 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37940 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
37950 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
37960 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
37970 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
37980 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
37990 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
379a0 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
379b0 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
379c0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
379d0 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
379e0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
379f0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
37a00 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
37a10 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
37a20 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
37a30 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
37a40 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
37a50 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
37a60 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
37a70 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
37a80 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
37a90 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
37aa0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
37ab0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
37ac0 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
37ad0 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
37ae0 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
37af0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
37b00 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
37b10 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
37b20 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
37b30 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
37b40 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
37b50 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
37b60 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
37b70 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
37b80 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
37b90 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
37ba0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
37bb0 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
37bc0 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
37bd0 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
37be0 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
37bf0 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
37c00 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
37c10 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
37c20 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
37c30 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
37c40 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
37c50 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
37c60 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
37c70 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
37c80 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
37c90 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
37ca0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64   char *sqlite3_d
37cb0 61 74 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  ata_directory;..
37cc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37cd0 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f  Test For Auto-Co
37ce0 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59  mmit Mode.** KEY
37cf0 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
37d00 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e  it mode}.**.** ^
37d10 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
37d20 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74  autocommit() int
37d30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
37d40 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65  on-zero or.** ze
37d50 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ro if the given 
37d60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37d70 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ion is or is not
37d80 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d   in autocommit m
37d90 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ode,.** respecti
37da0 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d  vely.  ^Autocomm
37db0 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
37dc0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75   default..** ^Au
37dd0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
37de0 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
37df0 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
37e00 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
37e10 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62   mode is re-enab
37e20 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54  led by a [COMMIT
37e30 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  ] or [ROLLBACK].
37e40 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69  .**.** If certai
37e50 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72  n kinds of error
37e60 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61  s occur on a sta
37e70 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
37e80 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a  multi-statement.
37e90 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28  ** transaction (
37ea0 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67  errors including
37eb0 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20   [SQLITE_FULL], 
37ec0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a  [SQLITE_IOERR],.
37ed0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
37ee0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
37ef0 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e  , and [SQLITE_IN
37f00 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74  TERRUPT]) then t
37f10 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  he.** transactio
37f20 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65  n might be rolle
37f30 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
37f40 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ally.  The only 
37f50 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f  way to.** find o
37f60 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74  ut whether SQLit
37f70 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
37f80 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20  rolled back the 
37f90 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65  transaction afte
37fa0 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73  r.** an error is
37fb0 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e   to use this fun
37fc0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
37fd0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
37fe0 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
37ff0 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
38000 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
38010 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
38020 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
38030 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
38040 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
38050 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
38060 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
38070 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
38080 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
38090 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
380a0 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
380b0 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
380c0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
380d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
380e0 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61  b_handle interfa
380f0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
38100 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
38110 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74  ion] handle.** t
38120 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61  o which a [prepa
38130 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
38140 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64  elongs.  ^The [d
38150 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38160 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  on].** returned 
38170 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
38180 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
38190 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
381a0 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77  ction].** that w
381b0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
381c0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
381d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
381e0 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20  _v2()] call (or 
381f0 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68  its variants) th
38200 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a  at was used to.*
38210 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  * create the sta
38220 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
38230 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71  rst place..*/.sq
38240 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
38250 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
38260 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
38270 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e  CAPI3REF: Return
38280 20 54 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f   The Filename Fo
38290 72 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e  r A Database Con
382a0 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
382b0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69  he sqlite3_db_fi
382c0 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65  lename(D,N) inte
382d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
382e0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c  pointer to a fil
382f0 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61  ename.** associa
38300 74 65 64 20 77 69 74 68 20 64 61 74 61 62 61 73  ted with databas
38310 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f  e N of connectio
38320 6e 20 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20  n D.  ^The main 
38330 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
38340 20 68 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d   has the name "m
38350 61 69 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20  ain".  If there 
38360 69 73 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64  is no attached d
38370 61 74 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65  atabase N on the
38380 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
38390 6e 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66  nection D, or if
383a0 20 64 61 74 61 62 61 73 65 20 4e 20 69 73 20 61   database N is a
383b0 20 74 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e   temporary or in
383c0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
383d0 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c  , then.** a NULL
383e0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
383f0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
38400 20 66 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e   filename return
38410 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
38420 69 6f 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75  ion is the outpu
38430 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c  t of the.** xFul
38440 6c 50 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64  lPathname method
38450 20 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20   of the [VFS].  
38460 5e 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  ^In other words,
38470 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
38480 20 77 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f   will be an abso
38490 6c 75 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65  lute pathname, e
384a0 76 65 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e  ven if the filen
384b0 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f  ame used.** to o
384c0 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
384d0 20 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20   originally was 
384e0 61 20 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76  a URI or relativ
384f0 65 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63  e pathname..*/.c
38500 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
38510 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73  e3_db_filename(s
38520 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73  qlite3 *db, cons
38530 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29  t char *zDbName)
38540 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38550 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 69 66 20  F: Determine if 
38560 61 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  a database is re
38570 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54  ad-only.**.** ^T
38580 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65  he sqlite3_db_re
38590 61 64 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e 74 65  adonly(D,N) inte
385a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 31 20  rface returns 1 
385b0 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
385c0 4e 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 74 69  N.** of connecti
385d0 6f 6e 20 44 20 69 73 20 72 65 61 64 2d 6f 6e 6c  on D is read-onl
385e0 79 2c 20 30 20 69 66 20 69 74 20 69 73 20 72 65  y, 0 if it is re
385f0 61 64 2f 77 72 69 74 65 2c 20 6f 72 20 2d 31 20  ad/write, or -1 
38600 69 66 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 20 74  if N is not.** t
38610 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 64 61 74  he name of a dat
38620 61 62 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 63 74  abase on connect
38630 69 6f 6e 20 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ion D..*/.int sq
38640 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c  lite3_db_readonl
38650 79 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63  y(sqlite3 *db, c
38660 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
38670 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
38680 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
38690 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
386a0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
386b0 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
386c0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
386d0 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
386e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
386f0 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
38700 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
38710 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
38720 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e  nection] pDb.  ^
38730 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
38740 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
38750 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
38760 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
38770 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
38780 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
38790 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
387a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
387b0 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e  tion pDb.  ^If n
387c0 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  o prepared state
387d0 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65  ment.** satisfie
387e0 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
387f0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
38800 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  , it returns NUL
38810 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61  L..**.** The [da
38820 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38830 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20