System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 3a10d0b1e25298f7ceefcd93915fbd871c94bc98:


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 23 69 66 6e 64 65 66 20 53 51  ndif..#ifndef SQ
0710: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e  LITE_API.# defin
0720: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e  e SQLITE_API.#en
0730: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  dif.../*.** Thes
0740: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0750: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0760: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0770: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0780: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0790: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
07a0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
07b0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
07c0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07d0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07e0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07f0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
0800: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
0810: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
0820: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0830: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0840: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0850: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0860: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0870: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0880: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
08a0: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
08b0: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
08c0: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08d0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08e0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08f0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
0900: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
0910: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
0920: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0930: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0940: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0950: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0960: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0970: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0980: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0990: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
09a0: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
09b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
09c0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09e0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09f0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
0a00: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
0a10: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
0a20: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a30: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a60: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a80: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a90: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0aa0: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0ac0: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0ad0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ae0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0af0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0b00: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0b10: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0b20: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b30: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b40: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b50: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b60: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b70: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b80: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b90: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0ba0: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0bb0: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0bc0: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0bd0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0be0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bf0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0c00: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0c10: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0c20: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c30: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c40: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c50: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c60: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c70: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c80: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c90: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0ca0: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0cb0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0cc0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0cd0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0ce0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cf0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0d00: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0d10: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0d20: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d30: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d40: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d50: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d60: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d70: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d80: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d90: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0da0: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0db0: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0dc0: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0dd0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0de0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0df0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0e00: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0e10: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0e20: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e40: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e50: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e60: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e70: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e80: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e90: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0ea0: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0eb0: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0ec0: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ed0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0ee0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ef0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0f00: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0f10: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0f20: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f30: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f40: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f50: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f60: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f70: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f80: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f90: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0fa0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0fb0: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0fc0: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fd0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fe0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0ff0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1010: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33  ERSION        "3
1020: 2e 38 2e 31 22 0a 23 64 65 66 69 6e 65 20 53 51  .8.1".#define SQ
1030: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1040: 42 45 52 20 33 30 30 38 30 30 31 0a 23 64 65 66  BER 3008001.#def
1050: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1060: 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 33 2d  E_ID      "2013-
1070: 30 38 2d 32 39 20 30 31 3a 30 39 3a 31 34 20 39  08-29 01:09:14 9
1080: 32 32 39 61 65 62 33 36 31 66 39 38 30 35 38 39  229aeb361f980589
1090: 34 33 32 31 33 32 37 64 30 35 61 62 61 38 35 35  4321327d05aba855
10a0: 62 38 37 39 39 66 33 22 0a 0a 2f 2a 0a 2a 2a 20  b8799f3"../*.** 
10b0: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
10c0: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69  me Library Versi
10d0: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45  on Numbers.** KE
10e0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
10f0: 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33  version, sqlite3
1100: 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20  _sourceid.**.** 
1110: 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  These interfaces
1120: 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d   provide the sam
1130: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  e information as
1140: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52   the [SQLITE_VER
1150: 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  SION],.** [SQLIT
1160: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1170: 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53  ], and [SQLITE_S
1180: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
1190: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a  rocessor macros.
11a0: 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63  ** but are assoc
11b0: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c  iated with the l
11c0: 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f  ibrary instead o
11d0: 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  f the header fil
11e0: 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a  e.  ^(Cautious.*
11f0: 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  * programmers mi
1200: 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65  ght include asse
1210: 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20  rt() statements 
1220: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61  in their applica
1230: 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66  tion to.** verif
1240: 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65  y that values re
1250: 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1260: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68  interfaces match
1270: 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a   the macros in.*
1280: 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e  * the header, an
1290: 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68  d thus insure th
12a0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
12b0: 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  on is.** compile
12c0: 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20  d with matching 
12d0: 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64  library and head
12e0: 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  er files..**.** 
12f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1300: 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c  >.** assert( sql
1310: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1320: 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45  number()==SQLITE
1330: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
1340: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
1350: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75  rcmp(sqlite3_sou
1360: 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53  rceid(),SQLITE_S
1370: 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a  OURCE_ID)==0 );.
1380: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d  ** assert( strcm
1390: 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  p(sqlite3_libver
13a0: 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45  sion(),SQLITE_VE
13b0: 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20  RSION)==0 );.** 
13c0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13d0: 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
13e0: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
13f0: 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  [] string consta
1400: 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  nt contains the 
1410: 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f  text of [SQLITE_
1420: 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72  VERSION].** macr
1430: 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  o.  ^The sqlite3
1440: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75  _libversion() fu
1450: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1460: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
1470: 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  ** to the sqlite
1480: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
1490: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68  ng constant.  Th
14a0: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
14b0: 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69  sion().** functi
14c0: 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66  on is provided f
14d0: 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73  or use in DLLs s
14e0: 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75  ince DLL users u
14f0: 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61  sually do not ha
1500: 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63  ve.** direct acc
1510: 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f  ess to string co
1520: 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74  nstants within t
1530: 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a  he DLL.  ^The.**
1540: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1550: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e  ion_number() fun
1560: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e  ction returns an
1570: 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74   integer equal t
1580: 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  o.** [SQLITE_VER
1590: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e  SION_NUMBER].  ^
15a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72  The sqlite3_sour
15b0: 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  ceid() function 
15c0: 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f  returns .** a po
15d0: 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e  inter to a strin
15e0: 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65  g constant whose
15f0: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61   value is the sa
1600: 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53  me as the .** [S
1610: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d  QLITE_SOURCE_ID]
1620: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1630: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  macro..**.** See
1640: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76   also: [sqlite_v
1650: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1660: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1670: 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
1680: 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  I SQLITE_EXTERN 
1690: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
16a0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53 51  e3_version[];.SQ
16b0: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
16c0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
16d0: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53  version(void);.S
16e0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16f0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1700: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51  urceid(void);.SQ
1710: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1720: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1730: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1740: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1750: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1760: 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69  Compilation Opti
1770: 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a  ons Diagnostics.
1780: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1790: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
17a0: 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e  _used() function
17b0: 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20   returns 0 or 1 
17c0: 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77  .** indicating w
17d0: 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69  hether the speci
17e0: 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20  fied option was 
17f0: 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63  defined at .** c
1800: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54  ompile time.  ^T
1810: 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69  he SQLITE_ prefi
1820: 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  x may be omitted
1830: 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70   from the .** op
1840: 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64  tion name passed
1850: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   to sqlite3_comp
1860: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1870: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .  .**.** ^The s
1880: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1890: 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74  tion_get() funct
18a0: 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61  ion allows itera
18b0: 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65  ting.** over the
18c0: 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73   list of options
18d0: 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e   that were defin
18e0: 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  ed at compile ti
18f0: 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69  me by.** returni
1900: 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70  ng the N-th comp
1910: 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile time option 
1920: 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69  string.  ^If N i
1930: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a  s out of range,.
1940: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
1950: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72  leoption_get() r
1960: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1970: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c  inter.  ^The SQL
1980: 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20  ITE_ .** prefix 
1990: 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
19a0: 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75  any strings retu
19b0: 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  rned by .** sqli
19c0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19d0: 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  n_get()..**.** ^
19e0: 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20  Support for the 
19f0: 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74  diagnostic funct
1a00: 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ions sqlite3_com
1a10: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a20: 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ).** and sqlite3
1a30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a40: 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74  et() may be omit
1a50: 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e  ted by specifyin
1a60: 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  g the .** [SQLIT
1a70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1a80: 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69  TION_DIAGS] opti
1a90: 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  on at compile ti
1aa0: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  me..**.** See al
1ab0: 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  so: SQL function
1ac0: 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c  s [sqlite_compil
1ad0: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20  eoption_used()] 
1ae0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63  and.** [sqlite_c
1af0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b00: 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d  ()] and the [com
1b10: 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61  pile_options pra
1b20: 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  gma]..*/.#ifndef
1b30: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d   SQLITE_OMIT_COM
1b40: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
1b50: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1b60: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1b70: 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74  ption_used(const
1b80: 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29   char *zOptName)
1b90: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
1ba0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1bb0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1bc0: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69  et(int N);.#endi
1bd0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
1be0: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
1bf0: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73  f The Library Is
1c00: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a   Threadsafe.**.*
1c10: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1c20: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
1c30: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72  tion returns zer
1c40: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  o if and only if
1c50: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63  .** SQLite was c
1c60: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74  ompiled with mut
1c70: 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74  exing code omitt
1c80: 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a  ed due to the.**
1c90: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1ca0: 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AFE] compile-tim
1cb0: 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73  e option being s
1cc0: 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53  et to 0..**.** S
1cd0: 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d  QLite can be com
1ce0: 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69  piled with or wi
1cf0: 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20  thout mutexes.  
1d00: 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  When.** the [SQL
1d10: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1d20: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1d30: 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20  acro is 1 or 2, 
1d40: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
1d50: 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74  nabled and SQLit
1d60: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e  e is threadsafe.
1d70: 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53    When the.** [S
1d80: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1d90: 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a  ] macro is 0, .*
1da0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72  * the mutexes ar
1db0: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68  e omitted.  With
1dc0: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c  out the mutexes,
1dd0: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a   it is not safe.
1de0: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65  ** to use SQLite
1df0: 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72   concurrently fr
1e00: 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  om more than one
1e10: 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45   thread..**.** E
1e20: 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20  nabling mutexes 
1e30: 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61  incurs a measura
1e40: 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ble performance 
1e50: 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69  penalty..** So i
1e60: 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74  f speed is of ut
1e70: 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c  most importance,
1e80: 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20   it makes sense 
1e90: 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  to disable.** th
1ea0: 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20  e mutexes.  But 
1eb0: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65  for maximum safe
1ec0: 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ty, mutexes shou
1ed0: 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  ld be enabled..*
1ee0: 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1ef0: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
1f00: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
1f10: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
1f20: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
1f30: 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70  e used by an app
1f40: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65  lication to make
1f50: 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a   sure that the.*
1f60: 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  * version of SQL
1f70: 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c  ite that it is l
1f80: 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77  inking against w
1f90: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1fa0: 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20  .** the desired 
1fb0: 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b  setting of the [
1fc0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fd0: 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  E] macro..**.** 
1fe0: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f  This interface o
1ff0: 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74  nly reports on t
2000: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
2010: 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a  mutex setting.**
2020: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
2030: 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67  THREADSAFE] flag
2040: 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
2050: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
2060: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
2070: 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20  FE=1 or =2 then 
2080: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62  mutexes are enab
2090: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62  led by default b
20a0: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c  ut.** can be ful
20b0: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20  ly or partially 
20c0: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
20d0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
20e0: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77  3_config()].** w
20f0: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53  ith the verbs [S
2100: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
2110: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c  GLETHREAD], [SQL
2120: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
2130: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b  THREAD],.** or [
2140: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2150: 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 74  TEX].  ^(The ret
2160: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
2170: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65  .** sqlite3_thre
2180: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
2190: 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65  n shows only the
21a0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65   compile-time se
21b0: 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65  tting of.** thre
21c0: 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61  ad safety, not a
21d0: 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e  ny run-time chan
21e0: 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74  ges to that sett
21f0: 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73  ing made by.** s
2200: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
2210: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2220: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2230: 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74  e from sqlite3_t
2240: 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69  hreadsafe().** i
2250: 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63  s unchanged by c
2260: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2270: 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a  config().)^.**.*
2280: 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61  * See the [threa
2290: 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d  ding mode] docum
22a0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
22b0: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
22c0: 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
22d0: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  PI int sqlite3_t
22e0: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b  hreadsafe(void);
22f0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2300: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
2310: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20  ction Handle.** 
2320: 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62  KEYWORDS: {datab
2330: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20  ase connection} 
2340: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2350: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63  tions}.**.** Eac
2360: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61  h open SQLite da
2370: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73  tabase is repres
2380: 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74  ented by a point
2390: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
23a0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71  e of.** the opaq
23b0: 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d  ue structure nam
23c0: 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49  ed "sqlite3".  I
23d0: 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74  t is useful to t
23e0: 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74  hink of an sqlit
23f0: 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73  e3.** pointer as
2400: 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65   an object.  The
2410: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2420: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2430: 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  16()], and.** [s
2440: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2450: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ] interfaces are
2460: 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72   its constructor
2470: 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  s, and [sqlite3_
2480: 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20  close()].** and 
2490: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76  [sqlite3_close_v
24a0: 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65 73  2()] are its des
24b0: 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65  tructors.  There
24c0: 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a   are many other.
24d0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28 73  ** interfaces (s
24e0: 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74  uch as.** [sqlit
24f0: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2500: 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
2510: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61  e_function()], a
2520: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2530: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74  usy_timeout()] t
2540: 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65  o name but three
2550: 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f  ) that are metho
2560: 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ds on an.** sqli
2570: 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74  te3 object..*/.t
2580: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2590: 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a  lite3 sqlite3;..
25a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25b0: 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54  64-Bit Integer T
25c0: 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
25d0: 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  : sqlite_int64 s
25e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a  qlite_uint64.**.
25f0: 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65  ** Because there
2600: 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61   is no cross-pla
2610: 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65  tform way to spe
2620: 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65  cify 64-bit inte
2630: 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c  ger types.** SQL
2640: 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70  ite includes typ
2650: 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74  edefs for 64-bit
2660: 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69   signed and unsi
2670: 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a  gned integers..*
2680: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2690: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
26a0: 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68  e3_uint64 are th
26b0: 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65  e preferred type
26c0: 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a   definitions..**
26d0: 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36   The sqlite_int6
26e0: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
26f0: 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75  t64 types are su
2700: 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b  pported for back
2710: 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69  wards.** compati
2720: 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  bility only..**.
2730: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2740: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2750: 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  _int64 types can
2760: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
2770: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
2780: 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37   -92233720368547
2790: 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33  75808 and +92233
27a0: 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69  72036854775807 i
27b0: 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a  nclusive.  ^The.
27c0: 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  ** sqlite3_uint6
27d0: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
27e0: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
27f0: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2800: 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  es .** between 0
2810: 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37   and +1844674407
2820: 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75  3709551615 inclu
2830: 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  sive..*/.#ifdef 
2840: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2850: 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49  E.  typedef SQLI
2860: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
2870: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
2880: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53  pedef unsigned S
2890: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
28a0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
28b0: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d  #elif defined(_M
28c0: 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e  SC_VER) || defin
28d0: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
28e0: 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74  .  typedef __int
28f0: 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  64 sqlite_int64;
2900: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
2910: 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  ned __int64 sqli
2920: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65  te_uint64;.#else
2930: 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20  .  typedef long 
2940: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
2950: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
2960: 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c   unsigned long l
2970: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75  ong int sqlite_u
2980: 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79  int64;.#endif.ty
2990: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74  pedef sqlite_int
29a0: 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64 sqlite3_int64
29b0: 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  ;.typedef sqlite
29c0: 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
29d0: 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49  uint64;../*.** I
29e0: 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  f compiling for 
29f0: 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74  a processor that
2a00: 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20   lacks floating 
2a10: 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a  point support,.*
2a20: 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74  * substitute int
2a30: 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e  eger for floatin
2a40: 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64  g-point..*/.#ifd
2a50: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46  ef SQLITE_OMIT_F
2a60: 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20  LOATING_POINT.# 
2a70: 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71  define double sq
2a80: 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64  lite3_int64.#end
2a90: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
2aa0: 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61  EF: Closing A Da
2ab0: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2ac0: 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  n.**.** ^The sql
2ad0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2ae0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2af0: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2b00: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2b10: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2b20: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2b30: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2b40: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2b50: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2b60: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
2b70: 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  f.** the [sqlite
2b80: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63  3] object is suc
2b90: 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f  cessfully destro
2ba0: 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f  yed and all asso
2bb0: 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72  ciated.** resour
2bc0: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
2bd0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ted..**.** ^If t
2be0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2bf0: 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69  ection is associ
2c00: 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61  ated with unfina
2c10: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a  lized prepared.*
2c20: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20  * statements or 
2c30: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74  unfinished sqlit
2c40: 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74  e3_backup object
2c50: 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  s then sqlite3_c
2c60: 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c  lose().** will l
2c70: 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73  eave the databas
2c80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
2c90: 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  n and return [SQ
2ca0: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e  LITE_BUSY]..** ^
2cb0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  If sqlite3_close
2cc0: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
2cd0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2ce0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2cf0: 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66 69  ents.** and unfi
2d00: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
2d10: 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65  ackups, then the
2d20: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2d30: 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20  tion becomes.** 
2d40: 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d  an unusable "zom
2d50: 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20  bie" which will 
2d60: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65  automatically be
2d70: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65   deallocated whe
2d80: 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72  n the.** last pr
2d90: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2da0: 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72   is finalized or
2db0: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
2dc0: 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66  3_backup is.** f
2dd0: 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71  inished.  The sq
2de0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2df0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
2e00: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77  tended for use w
2e10: 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67  ith.** host lang
2e20: 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67  uages that are g
2e30: 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64  arbage collected
2e40: 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20  , and where the 
2e50: 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a  order in which.*
2e60: 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72  * destructors ar
2e70: 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69  e called is arbi
2e80: 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  trary..**.** App
2e90: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
2ea0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2eb0: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61  ze | finalize] a
2ec0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
2ed0: 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71  tements],.** [sq
2ee0: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
2ef0: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
2f00: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e  LOB handles], an
2f10: 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  d .** [sqlite3_b
2f20: 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66  ackup_finish | f
2f30: 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69  inish] all [sqli
2f40: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
2f50: 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  cts associated.*
2f60: 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  * with the [sqli
2f70: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f  te3] object prio
2f80: 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20  r to attempting 
2f90: 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a  to close the obj
2fa0: 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c  ect.  ^If.** sql
2fb0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2fc0: 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  is called on a [
2fd0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2fe0: 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20  ion] that still 
2ff0: 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69  has.** outstandi
3000: 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ng [prepared sta
3010: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
3020: 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72  handles], and/or
3030: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
3040: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65  kup] objects the
3050: 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c  n it returns SQL
3060: 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64  ITE_OK but the d
3070: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3080: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3090: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
30a0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
30b0: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
30c0: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
30d0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
30e0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
30f0: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3100: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3110: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3120: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
3130: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
3140: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
3150: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3160: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3170: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3180: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3190: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
31a0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
31b0: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
31c0: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
31d0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
31e0: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
31f0: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3200: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3210: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3220: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
3230: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
3240: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
3250: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3260: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3270: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3280: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3290: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
32a0: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
32b0: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
32c0: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
32d0: 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  p..*/.SQLITE_API
32e0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f   int sqlite3_clo
32f0: 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  se(sqlite3*);.SQ
3300: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
3310: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71  ite3_close_v2(sq
3320: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
3330: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63  The type for a c
3340: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
3350: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67  ..** This is leg
3360: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74  acy and deprecat
3370: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75  ed.  It is inclu
3380: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
3390: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
33a0: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64  ity and is not d
33b0: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79  ocumented..*/.ty
33c0: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69  pedef int (*sqli
33d0: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f  te3_callback)(vo
33e0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20  id*,int,char**, 
33f0: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  char**);../*.** 
3400: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74  CAPI3REF: One-St
3410: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69  ep Query Executi
3420: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a  on Interface.**.
3430: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
3440: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3450: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65  is a convenience
3460: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
3470: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
3480: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
3490: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64  te3_step()], and
34a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
34b0: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61  ze()],.** that a
34c0: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61  llows an applica
34d0: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74  tion to run mult
34e0: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20  iple statements 
34f0: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75  of SQL.** withou
3500: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20  t having to use 
3510: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
3520: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
3530: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
3540: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20  rface runs zero 
3550: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e  or more UTF-8 en
3560: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f  coded,.** semico
3570: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c  lon-separate SQL
3580: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
3590: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20  ed into its 2nd 
35a0: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20  argument,.** in 
35b0: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74  the context of t
35c0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
35d0: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20  nection] passed 
35e0: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a  in as its 1st.**
35f0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
3600: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
3610: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64  ction of the 3rd
3620: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
3630: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3640: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
3650: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66   it is invoked f
3660: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72  or each result r
3670: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74  ow.** coming out
3680: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65   of the evaluate
3690: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
36a0: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
36b0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
36c0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c  e3_exec() is rel
36d0: 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ayed through to 
36e0: 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74  the 1st argument
36f0: 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c   of each.** call
3700: 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  back invocation.
3710: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
3720: 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  ck pointer to sq
3730: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3740: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f  is NULL, then no
3750: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65   callback is eve
3760: 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65  r invoked and re
3770: 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a  sult rows are.**
3780: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
3790: 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  ^If an error occ
37a0: 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61  urs while evalua
37b0: 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61  ting the SQL sta
37c0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
37d0: 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  nto.** sqlite3_e
37e0: 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63  xec(), then exec
37f0: 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72  ution of the cur
3800: 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73  rent statement s
3810: 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73  tops and.** subs
3820: 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74  equent statement
3830: 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20  s are skipped.  
3840: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
3850: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3860: 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f  _exec().** is no
3870: 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20  t NULL then any 
3880: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73  error message is
3890: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
38a0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  mory obtained.**
38b0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
38c0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73  alloc()] and pas
38d0: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68  sed back through
38e0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
38f0: 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  er..** To avoid 
3900: 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68  memory leaks, th
3910: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
3920: 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  ould invoke [sql
3930: 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
3940: 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  on error message
3950: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
3960: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  d through the 5t
3970: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a  h parameter of.*
3980: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  * of sqlite3_exe
3990: 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72  c() after the er
39a0: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
39b0: 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ng is no longer 
39c0: 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  needed..** ^If t
39d0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
39e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
39f0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  () is not NULL a
3a00: 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  nd no errors.** 
3a10: 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69  occur, then sqli
3a20: 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20  te3_exec() sets 
3a30: 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69  the pointer in i
3a40: 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  ts 5th parameter
3a50: 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f   to.** NULL befo
3a60: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
3a70: 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74  .** ^If an sqlit
3a80: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3a90: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
3aa0: 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ero, the sqlite3
3ab0: 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69  _exec().** routi
3ac0: 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  ne returns SQLIT
3ad0: 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20  E_ABORT without 
3ae0: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c  invoking the cal
3af0: 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a  lback again and.
3b00: 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69  ** without runni
3b10: 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  ng any subsequen
3b20: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
3b30: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64  ..**.** ^The 2nd
3b40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3b50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3b60: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3b70: 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  n is the.** numb
3b80: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
3b90: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54   the result.  ^T
3ba0: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3bb0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3bc0: 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63  xec().** callbac
3bd0: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3be0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3bf0: 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73  ings obtained as
3c00: 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c   if from.** [sql
3c10: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
3c20: 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63  ()], one for eac
3c30: 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61  h column.  ^If a
3c40: 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a  n element of a.*
3c50: 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20  * result row is 
3c60: 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
3c70: 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69  rresponding stri
3c80: 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  ng pointer for t
3c90: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
3ca0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
3cb0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
3cc0: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d    ^The 4th argum
3cd0: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71  ent to the.** sq
3ce0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3cf0: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
3d00: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3d10: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65   strings where e
3d20: 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70  ach.** entry rep
3d30: 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65  resents the name
3d40: 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e   of correspondin
3d50: 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  g result column 
3d60: 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  as obtained.** f
3d70: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
3d80: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a  umn_name()]..**.
3d90: 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70  ** ^If the 2nd p
3da0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3db0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20  te3_exec() is a 
3dc0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20  NULL pointer, a 
3dd0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e  pointer.** to an
3de0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f   empty string, o
3df0: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  r a pointer that
3e00: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77   contains only w
3e10: 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72  hitespace and/or
3e20: 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74   .** SQL comment
3e30: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73  s, then no SQL s
3e40: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76  tatements are ev
3e50: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20  aluated and the 
3e60: 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e  database.** is n
3e70: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a  ot changed..**.*
3e80: 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a  * Restrictions:.
3e90: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
3ea0: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3eb0: 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  on must insure t
3ec0: 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61  hat the 1st para
3ed0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3ee0: 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20  _exec().**      
3ef0: 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f  is a valid and o
3f00: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
3f10: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c  nnection]..** <l
3f20: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3f30: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  on must not clos
3f40: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
3f50: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
3f60: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
3f70: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3f80: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f90: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3fa0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3fb0: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
3fc0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
3fd0: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
3fe0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
3ff0: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
4000: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
4010: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
4020: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
4030: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
4040: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
4050: 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l>.*/.SQLITE_API
4060: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65   int sqlite3_exe
4070: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  c(.  sqlite3*,  
4080: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
40b0: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
40c0: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20  har *sql,       
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40e0: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
40f0: 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
4100: 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28  int (*callback)(
4110: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
4120: 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61  ,char**),  /* Ca
4130: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
4140: 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20  */.  void *,    
4150: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4170: 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20  /* 1st argument 
4180: 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20  to callback */. 
4190: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20   char **errmsg  
41a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
41c0: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
41d0: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   here */.);../*.
41e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
41f0: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
4200: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b  WORDS: SQLITE_OK
4210: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65   {error code} {e
4220: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4230: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
4240: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63   code} {result c
4250: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79  odes}.**.** Many
4260: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e   SQLite function
4270: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65  s return an inte
4280: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ger result code 
4290: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f  from the set sho
42a0: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72  wn.** here in or
42b0: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20  der to indicate 
42c0: 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75  success or failu
42d0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72  re..**.** New er
42e0: 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65  ror codes may be
42f0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
4300: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4310: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ite..**.** See a
4320: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  lso: [SQLITE_IOE
4330: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
4340: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
4350: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74  ,.** [sqlite3_vt
4360: 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
4370: 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41  ] [SQLITE_ROLLBA
4380: 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  CK | result code
4390: 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s]..*/.#define S
43a0: 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20  QLITE_OK        
43b0: 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73     0   /* Succes
43c0: 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f  sful result */./
43d0: 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65  * beginning-of-e
43e0: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64  rror-codes */.#d
43f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52  efine SQLITE_ERR
4400: 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a  OR        1   /*
4410: 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69   SQL error or mi
4420: 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a  ssing database *
4430: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4440: 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20  _INTERNAL     2 
4450: 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f    /* Internal lo
4460: 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c  gic error in SQL
4470: 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ite */.#define S
4480: 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20  QLITE_PERM      
4490: 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73     3   /* Access
44a0: 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69   permission deni
44b0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
44c0: 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20  LITE_ABORT      
44d0: 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63    4   /* Callbac
44e0: 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73  k routine reques
44f0: 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a  ted an abort */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
4510: 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20  USY         5   
4520: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4530: 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  file is locked *
4540: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4550: 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20  _LOCKED       6 
4560: 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20    /* A table in 
4570: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
4580: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
4590: 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20  e SQLITE_NOMEM  
45a0: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d        7   /* A m
45b0: 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a  alloc() failed *
45c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45d0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20  _READONLY     8 
45e0: 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20    /* Attempt to 
45f0: 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79  write a readonly
4600: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
4610: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
4620: 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20  RRUPT    9   /* 
4630: 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e  Operation termin
4640: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
4650: 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64  interrupt()*/.#d
4660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4670: 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a  RR       10   /*
4680: 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69   Some kind of di
4690: 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63  sk I/O error occ
46a0: 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  urred */.#define
46b0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20   SQLITE_CORRUPT 
46c0: 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20      11   /* The 
46d0: 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d  database disk im
46e0: 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64  age is malformed
46f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4700: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31  TE_NOTFOUND    1
4710: 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f  2   /* Unknown o
4720: 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33  pcode in sqlite3
4730: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20  _file_control() 
4740: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4750: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33  E_FULL        13
4760: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20     /* Insertion 
4770: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64  failed because d
4780: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20  atabase is full 
4790: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
47a0: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34  E_CANTOPEN    14
47b0: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20     /* Unable to 
47c0: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
47d0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
47e0: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f  e SQLITE_PROTOCO
47f0: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74  L    15   /* Dat
4800: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
4810: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
4820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
4830: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
4840: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4850: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4860: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4870: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4880: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4890: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
48a0: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
48b0: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
48c0: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
48d0: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
48f0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
4900: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
4910: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
4920: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
4930: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
4940: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4950: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4960: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4970: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4980: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4990: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
49a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
49b0: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
49c0: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
49d0: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
49e0: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
49f0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
4a00: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
4a10: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
4a20: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4a30: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
4a40: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4a50: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4a60: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4a80: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4a90: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4aa0: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4ab0: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4ad0: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4ae0: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
4af0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
4b00: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
4b20: 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e  E      27   /* N
4b30: 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f  otifications fro
4b40: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4b60: 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38  E_WARNING     28
4b70: 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66     /* Warnings f
4b80: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4b90: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4ba0: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
4bb0: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
4bc0: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
4bd0: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
4be0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
4bf0: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
4c00: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4c10: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
4c20: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
4c30: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
4c40: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
4c50: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
4c60: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
4c70: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4c80: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  ed error code} {
4c90: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
4ca0: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
4cb0: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73  S: {extended res
4cc0: 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e  ult code} {exten
4cd0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ce0: 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64  }.**.** In its d
4cf0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
4d00: 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49  tion, SQLite API
4d10: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
4d20: 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67   one of 26 integ
4d30: 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  er.** [SQLITE_OK
4d40: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
4d50: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4d60: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4d70: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4d80: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4d90: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4da0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4db0: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4dc0: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4dd0: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4de0: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4df0: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4e00: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4e10: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4e20: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4e30: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4e40: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4e50: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4e60: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
4e70: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
4e80: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
4e90: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
4ea0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
4eb0: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
4ec0: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
4ed0: 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62  t codes are enab
4ee0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
4ef0: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
4f00: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
4f10: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
4f20: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
4f30: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
4f40: 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20  s()] API..**.** 
4f50: 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69  Some of the avai
4f60: 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72  lable extended r
4f70: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4f80: 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20  listed here..** 
4f90: 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 74  One may expect t
4fa0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
4fb0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4fc0: 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e  es will be expan
4fd0: 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20  d.** over time. 
4fe0: 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 75   Software that u
4ff0: 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 73  ses extended res
5000: 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64  ult codes should
5010: 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65   expect.** to se
5020: 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64  e new result cod
5030: 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  es in future rel
5040: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
5050: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
5060: 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65  E_OK result code
5070: 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65   will never be e
5080: 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c  xtended.  It wil
5090: 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65  l always.** be e
50a0: 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a  xactly zero..*/.
50b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
50c0: 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20  OERR_READ       
50d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
50e0: 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23  OERR | (1<<8)).#
50f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5100: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20  ERR_SHORT_READ  
5110: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5120: 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ERR | (2<<8)).#d
5130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5140: 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20  RR_WRITE        
5150: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5160: 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  RR | (3<<8)).#de
5170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5180: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
5190: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51a0: 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  R | (4<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51c0: 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20  _DIR_FSYNC      
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51e0: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5200: 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20  TRUNCATE        
5210: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5220: 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (6<<8)).#defin
5230: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
5240: 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20  STAT            
5250: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5260: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
5270: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e   SQLITE_IOERR_UN
5280: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5290: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
52a0: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c  SQLITE_IOERR_RDL
52c0: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52e0: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
52f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
5300: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53  TE            (S
5310: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5320: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5330: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
5340: 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53  KED           (S
5350: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5360: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5370: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45  QLITE_IOERR_NOME
5380: 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  M             (S
5390: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
53a0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
53b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45  QLITE_IOERR_ACCE
53c0: 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53  SS            (S
53d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
53e0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
53f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43  QLITE_IOERR_CHEC
5400: 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53  KRESERVEDLOCK (S
5410: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5420: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5430: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b  QLITE_IOERR_LOCK
5440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5450: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5460: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5470: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53  QLITE_IOERR_CLOS
5480: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  E             (S
5490: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
54a0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
54b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
54c0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53  CLOSE         (S
54d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
54e0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
54f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f  QLITE_IOERR_SHMO
5500: 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53  PEN           (S
5510: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5520: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5530: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53  QLITE_IOERR_SHMS
5540: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53  IZE           (S
5550: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5560: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
5570: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c  QLITE_IOERR_SHML
5580: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53  OCK           (S
5590: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
55a0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
55b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d  QLITE_IOERR_SHMM
55c0: 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AP            (S
55d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
55e0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
55f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b  QLITE_IOERR_SEEK
5600: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5610: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
5620: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5630: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
5640: 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53  TE_NOENT      (S
5650: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
5660: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5670: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50  QLITE_IOERR_MMAP
5680: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5690: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
56a0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
56b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54  QLITE_IOERR_GETT
56c0: 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53  EMPPATH       (S
56d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
56e0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
56f0: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41  QLITE_LOCKED_SHA
5700: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53  REDCACHE      (S
5710: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20  QLITE_LOCKED |  
5720: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5730: 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f  SQLITE_BUSY_RECO
5740: 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28  VERY           (
5750: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
5760: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5770: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41   SQLITE_BUSY_SNA
5780: 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20  PSHOT           
5790: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
57a0: 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (2<<8)).#defin
57b0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
57c0: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20  N_NOTEMPDIR     
57d0: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
57e0: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  N | (1<<8)).#def
57f0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5800: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20  PEN_ISDIR       
5810: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5820: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  PEN | (2<<8)).#d
5830: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5840: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20  TOPEN_FULLPATH  
5850: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5860: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a  TOPEN | (3<<8)).
5870: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5880: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
5890: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
58a0: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
58b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58c0: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
58d0: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
58e0: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
58f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5900: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
5910: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
5920: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
5930: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5940: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c  ITE_READONLY_ROL
5950: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c  LBACK       (SQL
5960: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5970: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5980: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5990: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
59a0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
59b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
59c0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
59d0: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
59e0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
59f0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5a00: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5a10: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5a20: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5a30: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5a40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5a50: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
5a60: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5a70: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5a80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a90: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5aa0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5ab0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5ac0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ad0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5ae0: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
5af0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5b00: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5b10: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5b20: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
5b30: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5b40: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
5b50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5b60: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
5b70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b80: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
5b90: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5ba0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
5bb0: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
5bc0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
5bd0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5be0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5bf0: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
5c00: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5c10: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
5c20: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5c30: 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20  RECOVER_WAL     
5c40: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5c50: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5c60: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5c70: 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b  RECOVER_ROLLBACK
5c80: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5c90: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5ca0: 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47  e SQLITE_WARNING
5cb0: 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20  _AUTOINDEX      
5cc0: 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47   (SQLITE_WARNING
5cd0: 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a   | (1<<8))../*.*
5ce0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
5cf0: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
5d00: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Operations.**.**
5d10: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
5d20: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
5d30: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a  or use in the.**
5d40: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
5d50: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
5d60: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
5d70: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
5d80: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
5d90: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5da0: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
5db0: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
5dc0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
5dd0: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
5de0: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72  00001  /* Ok for
5df0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5e00: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5e10: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5e20: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
5e30: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72  00002  /* Ok for
5e40: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5e50: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5e60: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5e70: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5e80: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72  00004  /* Ok for
5e90: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5ea0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5eb0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
5ec0: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
5ed0: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e  00008  /* VFS on
5ee0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
5ef0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
5f00: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
5f10: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00010  /* VFS on
5f20: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
5f30: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52  LITE_OPEN_AUTOPR
5f40: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30  OXY        0x000
5f50: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00020  /* VFS on
5f60: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
5f70: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20  LITE_OPEN_URI   
5f80: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5f90: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00040  /* Ok for
5fa0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5fb0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5fc0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59  LITE_OPEN_MEMORY
5fd0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5fe0: 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00080  /* Ok for
5ff0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6000: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6010: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
6020: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
6030: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00100  /* VFS on
6040: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6050: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
6060: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
6070: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00200  /* VFS on
6080: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6090: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
60a0: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
60b0: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00400  /* VFS on
60c0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
60d0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
60e0: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
60f0: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00800  /* VFS on
6100: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6110: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
6120: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
6130: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  01000  /* VFS on
6140: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6150: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
6160: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
6170: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  02000  /* VFS on
6180: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6190: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
61a0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
61b0: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  04000  /* VFS on
61c0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
61d0: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
61e0: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
61f0: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  08000  /* Ok for
6200: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6210: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6220: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
6230: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
6240: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  10000  /* Ok for
6250: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6260: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6270: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
6280: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30  CACHE      0x000
6290: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  20000  /* Ok for
62a0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
62b0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
62c0: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
62d0: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30  ECACHE     0x000
62e0: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  40000  /* Ok for
62f0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6300: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6310: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20  LITE_OPEN_WAL   
6320: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6330: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  80000  /* VFS on
6340: 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76  ly */../* Reserv
6350: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
6360: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6370: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
6380: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
6390: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
63a0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
63b0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
63c0: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
63d0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
63e0: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
63f0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
6400: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
6410: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ctor of these.**
6420: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
6430: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
6440: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
6450: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
6460: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
6470: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
6480: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
6490: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
64a0: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
64b0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
64c0: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
64d0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
64e0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
64f0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
6500: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6510: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
6520: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
6530: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
6540: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
6550: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
6560: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
6570: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
6580: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
6590: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
65a0: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
65b0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
65c0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
65d0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
65e0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
65f0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
6600: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
6610: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
6620: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
6630: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
6640: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
6650: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
6660: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
6670: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6680: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
6690: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
66a0: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
66b0: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
66c0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
66d0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
66e0: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
66f0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6700: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
6710: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6720: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
6730: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
6740: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
6750: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
6760: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
6770: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
6780: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
6790: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
67a0: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
67b0: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
67c0: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
67d0: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
67e0: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
67f0: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
6800: 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23   unchanged..*/.#
6810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6820: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
6830: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6840: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
6850: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6860: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
6870: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
6880: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6890: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
68a0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
68b0: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
68c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
68d0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
68e0: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
68f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6900: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
6910: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
6920: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6930: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
6940: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6950: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
6960: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6970: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
6980: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
6990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
69a0: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
69b0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
69c0: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
69d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
69e0: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
69f0: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
6a00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6a10: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
6a20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6a30: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
6a40: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6a50: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
6a60: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
6a70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a80: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
6a90: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
6aa0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6ab0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6ac0: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
6ad0: 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00001000../*.**
6ae0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
6af0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
6b00: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
6b10: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
6b20: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6b30: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
6b40: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
6b50: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
6b60: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6b70: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
6b80: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6b90: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6ba0: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
6bb0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
6bc0: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6bd0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
6be0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
6bf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6c00: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
6c10: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
6c20: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
6c30: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6c40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6c50: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
6c60: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
6c70: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
6c80: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
6c90: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
6ca0: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
6cb0: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
6cc0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6cd0: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
6ce0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
6cf0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
6d00: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6d10: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
6d20: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
6d30: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
6d40: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
6d50: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
6d60: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
6d70: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
6d80: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
6d90: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
6da0: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
6db0: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
6dc0: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
6dd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6de0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
6df0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
6e00: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
6e10: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
6e20: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
6e30: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
6e40: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6e50: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
6e60: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
6e70: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
6e80: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
6e90: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
6ea0: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
6eb0: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
6ec0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6ed0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6ee0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
6ef0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
6f00: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6f10: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
6f20: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6f30: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
6f40: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
6f50: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
6f60: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
6f70: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
6f80: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
6f90: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
6fa0: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
6fb0: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
6fc0: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
6fd0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6fe0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6ff0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
7000: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
7010: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
7020: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
7030: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
7040: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
7050: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
7060: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
7070: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
7080: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
7090: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
70a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
70b0: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
70c0: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
70d0: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
70e0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
70f0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
7100: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
7110: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
7120: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
7130: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
7140: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
7150: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
7160: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
7170: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7180: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
7190: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
71a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
71b0: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
71c0: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
71d0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
71e0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
71f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7200: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
7210: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
7220: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
7230: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
7240: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
7250: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
7260: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
7270: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
7280: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
7290: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
72a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
72b0: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
72c0: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
72d0: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
72e0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
72f0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
7300: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
7310: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
7320: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
7330: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
7340: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7350: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
7360: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
7370: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
7380: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
7390: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
73a0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
73b0: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
73c0: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
73d0: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
73e0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
73f0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
7400: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
7410: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
7420: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
7430: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7440: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
7450: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
7460: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
7470: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
7480: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7490: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
74a0: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
74b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
74c0: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
74d0: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
74e0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
74f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7500: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
7510: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
7520: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
7530: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
7540: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
7550: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
7560: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
7570: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
7580: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
7590: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
75a0: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
75b0: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
75c0: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
75d0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
75e0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
75f0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7600: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
7610: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
7620: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
7630: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7640: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
7650: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
7660: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
7670: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7680: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
7690: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
76a0: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
76b0: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
76c0: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
76d0: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
76e0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
76f0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
7700: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7710: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
7720: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7730: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
7740: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
7750: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7760: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
7770: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
7780: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
7790: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
77a0: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
77b0: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
77c0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
77d0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
77e0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
77f0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
7800: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
7810: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
7820: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
7830: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
7840: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
7850: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
7860: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
7870: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
7880: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
7890: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
78a0: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
78b0: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
78c0: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
78d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
78e0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
78f0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
7900: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
7910: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
7920: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
7930: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7940: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
7950: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
7960: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
7970: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
7980: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
7990: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
79a0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
79b0: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
79c0: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
79d0: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
79e0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
79f0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
7a00: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
7a10: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
7a20: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
7a30: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
7a40: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
7a50: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
7a60: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
7a70: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
7a80: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
7a90: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
7aa0: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
7ab0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
7ac0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
7ad0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
7ae0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
7af0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
7b00: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7b10: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
7b20: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
7b30: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
7b40: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7b50: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
7b60: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
7b70: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
7b80: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
7b90: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
7ba0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
7bb0: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
7bc0: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
7bd0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
7be0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
7bf0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
7c00: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
7c10: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
7c20: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
7c30: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
7c40: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7c50: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
7c60: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
7c70: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
7c80: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
7c90: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
7ca0: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
7cb0: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
7cc0: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
7cd0: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
7ce0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
7cf0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
7d00: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
7d10: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
7d20: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
7d30: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
7d40: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
7d50: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
7d60: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  * A [SQLITE_FCNT
7d70: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69  L_LOCKSTATE | li
7d80: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
7d90: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
7da0: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
7db0: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
7dc0: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
7dd0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7de0: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
7df0: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
7e00: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
7e10: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20  oid conflicts.  
7e20: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
7e30: 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ons should.** re
7e40: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  turn [SQLITE_NOT
7e50: 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20  FOUND] for file 
7e60: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
7e70: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
7e80: 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a  .** recognize..*
7e90: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
7ea0: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
7eb0: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
7ec0: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
7ed0: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
7ee0: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
7ef0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
7f00: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
7f10: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
7f20: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
7f30: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
7f40: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
7f50: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
7f60: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
7f70: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
7f80: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
7f90: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
7fa0: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
7fb0: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
7fc0: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
7fd0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
7fe0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7ff0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
8000: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8010: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
8020: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8030: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
8040: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8050: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
8060: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8070: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
8080: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8090: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
80a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
80b0: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
80c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
80d0: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
80e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
80f0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
8100: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8110: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
8120: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8130: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
8140: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
8150: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
8160: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
8170: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
8180: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
8190: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
81a0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
81b0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
81c0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
81d0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
81e0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
81f0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
8200: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
8210: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
8220: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
8230: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
8240: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
8250: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8260: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
8270: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
8280: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
8290: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
82a0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
82b0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
82c0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
82d0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
82e0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
82f0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
8300: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
8310: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
8320: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
8330: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
8340: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
8350: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
8360: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
8370: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
8380: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52  e()..**.** If xR
8390: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51  ead() returns SQ
83a0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
83b0: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c  _READ it must al
83c0: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68  so fill.** in th
83d0: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e  e unread portion
83e0: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  s of the buffer 
83f0: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56  with zeros.  A V
8400: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73  FS that.** fails
8410: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
8420: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20  ort reads might 
8430: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48  seem to work.  H
8440: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75  owever,.** failu
8450: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  re to zero-fill 
8460: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c  short reads will
8470: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64   eventually lead
8480: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   to.** database 
8490: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74  corruption..*/.t
84a0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
84b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
84c0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
84d0: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
84e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b  te3_io_methods {
84f0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
8500: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
8510: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8520: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28  .  int (*xRead)(
8530: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76  sqlite3_file*, v
8540: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
8550: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8560: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57  fst);.  int (*xW
8570: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  rite)(sqlite3_fi
8580: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  le*, const void*
8590: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
85a0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
85b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63  ;.  int (*xTrunc
85c0: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ate)(sqlite3_fil
85d0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
85e0: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  4 size);.  int (
85f0: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
8600: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73  file*, int flags
8610: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
8620: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
8630: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8640: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e  64 *pSize);.  in
8650: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74  t (*xLock)(sqlit
8660: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
8670: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29    int (*xUnlock)
8680: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8690: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  int);.  int (*xC
86a0: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
86b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
86c0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
86d0: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e    int (*xFileCon
86e0: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69  trol)(sqlite3_fi
86f0: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  le*, int op, voi
8700: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  d *pArg);.  int 
8710: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73  (*xSectorSize)(s
8720: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8730: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68   int (*xDeviceCh
8740: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73  aracteristics)(s
8750: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8760: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8770: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8780: 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69  version 1 */.  i
8790: 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71  nt (*xShmMap)(sq
87a0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
87b0: 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20   iPg, int pgsz, 
87c0: 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69  int, void volati
87d0: 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  le**);.  int (*x
87e0: 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  ShmLock)(sqlite3
87f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73  _file*, int offs
8800: 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66  et, int n, int f
8810: 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a  lags);.  void (*
8820: 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c  xShmBarrier)(sql
8830: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
8840: 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28  nt (*xShmUnmap)(
8850: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8860: 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a  nt deleteFlag);.
8870: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
8880: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
8890: 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20   version 2 */.  
88a0: 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71  int (*xFetch)(sq
88b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
88c0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
88d0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64  , int iAmt, void
88e0: 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a   **pp);.  int (*
88f0: 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65  xUnfetch)(sqlite
8900: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
8910: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f  _int64 iOfst, vo
8920: 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74  id *p);.  /* Met
8930: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
8940: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
8950: 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74   3 */.  /* Addit
8960: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61  ional methods ma
8970: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
8980: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f  ture releases */
8990: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
89a0: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69  REF: Standard Fi
89b0: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64  le Control Opcod
89c0: 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  es.**.** These i
89d0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
89e0: 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72   are opcodes for
89f0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
8a00: 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  l method.** of t
8a10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
8a20: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61  ethods] object a
8a30: 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  nd for the [sqli
8a40: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8a50: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
8a60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
8a70: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
8a80: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
8a90: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
8aa0: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
8ab0: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
8ac0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
8ad0: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
8ae0: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
8af0: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
8b00: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
8b10: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
8b20: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
8b30: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
8b40: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
8b50: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
8b60: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
8b70: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
8b80: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
8b90: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
8ba0: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
8bb0: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
8bc0: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
8bd0: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f  ng testing and o
8be0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
8bf0: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
8c00: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73  QLITE_TEST.** is
8c10: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c   defined..** <ul
8c20: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  >.** <li>[[SQLIT
8c30: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
8c40: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
8c50: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
8c60: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
8c70: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
8c80: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
8c90: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
8ca0: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
8cb0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
8cc0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
8cd0: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
8ce0: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
8cf0: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
8d00: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
8d10: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
8d20: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
8d30: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
8d40: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
8d50: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
8d60: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
8d70: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
8d80: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
8d90: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
8da0: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
8db0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
8dc0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
8dd0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8de0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
8df0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8e00: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
8e10: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8e20: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
8e30: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
8e40: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
8e50: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
8e60: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
8e70: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
8e80: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
8e90: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
8ea0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
8eb0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8ec0: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
8ed0: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
8ee0: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
8ef0: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
8f00: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
8f10: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
8f20: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
8f30: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
8f40: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
8f50: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
8f60: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
8f70: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
8f80: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
8f90: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
8fa0: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
8fb0: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
8fc0: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
8fd0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8fe0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
8ff0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9000: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9010: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
9020: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9030: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
9040: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9050: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9060: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
9070: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
9080: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
9090: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
90a0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63  e_control()] doc
90b0: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  umentation for.*
90c0: 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
90d0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
90e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
90f0: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
9100: 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49  ].** ^(The [SQLI
9110: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
9120: 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73  ITTED] opcode is
9130: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9140: 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69  nally by.** SQLi
9150: 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61  te and sent to a
9160: 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63  ll VFSes in plac
9170: 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74  e of a call to t
9180: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a  he xSync method.
9190: 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  ** when the data
91a0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
91b0: 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  has [PRAGMA sync
91c0: 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20  hronous] set to 
91d0: 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73  OFF.)^.** Some s
91e0: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
91f0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9200: 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70  l in order to op
9210: 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a  erate correctly.
9220: 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20  ** when [PRAGMA 
9230: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52  synchronous | PR
9240: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
9250: 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75  =OFF] is set, bu
9260: 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73  t most .** VFSes
9270: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
9280: 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f  s signal and sho
9290: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
92a0: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
92b0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
92c0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
92d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
92e0: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
92f0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73  his.** opcode as
9300: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
9310: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
9320: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
9330: 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20  alized VFSes.** 
9340: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
9350: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
9360: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
9370: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a  IN32_AV_RETRY]].
9380: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
9390: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
93a0: 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETRY] opcode is 
93b0: 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
93c0: 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72  e automatic.** r
93d0: 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20  etry counts and 
93e0: 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65  intervals for ce
93f0: 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f  rtain disk I/O o
9400: 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68  perations for th
9410: 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46  e.** windows [VF
9420: 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70  S] in order to p
9430: 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73  rovide robustnes
9440: 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63  s in the presenc
9450: 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72  e of.** anti-vir
9460: 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79  us programs.  By
9470: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69   default, the wi
9480: 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72  ndows VFS will r
9490: 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a  etry file read,.
94a0: 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61  ** file write, a
94b0: 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f  nd file delete o
94c0: 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20  perations up to 
94d0: 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61  10 times, with a
94e0: 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20   delay.** of 25 
94f0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66  milliseconds bef
9500: 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65  ore the first re
9510: 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65  try and with the
9520: 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e   delay increasin
9530: 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74  g.** by an addit
9540: 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65  ional 25 millise
9550: 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20  conds with each 
9560: 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79  subsequent retry
9570: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
9580: 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74  e allows these t
9590: 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65  wo values (10 re
95a0: 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c  tries and 25 mil
95b0: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c  liseconds of del
95c0: 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a  ay).** to be adj
95d0: 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75  usted.  The valu
95e0: 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66  es are changed f
95f0: 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20  or all database 
9600: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77  connections.** w
9610: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70  ithin the same p
9620: 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67  rocess.  The arg
9630: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
9640: 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f  er to an array o
9650: 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72  f two.** integer
9660: 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73  s where the firs
9670: 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20  t integer i the 
9680: 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20  new retry count 
9690: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  and the second.*
96a0: 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65  * integer is the
96b0: 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68   delay.  If eith
96c0: 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65  er integer is ne
96d0: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
96e0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e   setting.** is n
96f0: 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69  ot changed but i
9700: 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72  nstead the prior
9710: 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73   value of that s
9720: 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65  etting is writte
9730: 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72  n.** into the ar
9740: 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77  ray entry, allow
9750: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20  ing the current 
9760: 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74  retry settings t
9770: 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67  o be.** interrog
9780: 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61  ated.  The zDbNa
9790: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
97a0: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  ignored..**.** <
97b0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
97c0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a  L_PERSIST_WAL]].
97d0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
97e0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
97f0: 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  L] opcode is use
9800: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
9810: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
9820: 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65  ent [WAL | Write
9830: 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74   Ahead Log] sett
9840: 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ing.  By default
9850: 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a  , the auxiliary.
9860: 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c  ** write ahead l
9870: 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  og and shared me
9880: 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20  mory files used 
9890: 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  for transaction 
98a0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61  control.** are a
98b0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
98c0: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61  eted when the la
98d0: 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  test connection 
98e0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
98f0: 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74  ** closes.  Sett
9900: 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57  ing persistent W
9910: 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74  AL mode causes t
9920: 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65  hose files to pe
9930: 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63  rsist after.** c
9940: 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e  lose.  Persistin
9950: 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75  g the files is u
9960: 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72  seful when other
9970: 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20   processes that 
9980: 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77  do not.** have w
9990: 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20  rite permission 
99a0: 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  on the directory
99b0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
99c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
99d0: 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68  nt.** to read th
99e0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
99f0: 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20   as the WAL and 
9a00: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
9a10: 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a  les must exist.*
9a20: 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74  * in order for t
9a30: 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62  he database to b
9a40: 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  e readable.  The
9a50: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
9a60: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
9a70: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9a80: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
9a90: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
9aa0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
9ab0: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
9ac0: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
9ad0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57  ble persistent W
9ae0: 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  AL mode or 1 to 
9af0: 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  enable persisten
9b00: 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20  t.** WAL mode.  
9b10: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
9b20: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
9b30: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
9b40: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
9b50: 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65   WAL persistence
9b60: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
9b70: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9b80: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
9b90: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
9ba0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
9bb0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
9bc0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
9bd0: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
9be0: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
9bf0: 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d  tent "powersafe-
9c00: 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50  overwrite" or "P
9c10: 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54  SOW" setting.  T
9c20: 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a  he PSOW setting.
9c30: 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  ** determines th
9c40: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  e [SQLITE_IOCAP_
9c50: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
9c60: 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a  ITE] bit of the.
9c70: 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63  ** xDeviceCharac
9c80: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
9c90: 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  s. The fourth pa
9ca0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9cb0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9cc0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9cd0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9ce0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9cf0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9d00: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9d10: 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64  o disable zero-d
9d20: 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20  amage mode or 1 
9d30: 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64  to enable zero-d
9d40: 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20  amage.** mode.  
9d50: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
9d60: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
9d70: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
9d80: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
9d90: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
9da0: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
9db0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9dc0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  NTL_OVERWRITE]].
9dd0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
9de0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
9df0: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b   opcode is invok
9e00: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74  ed by SQLite aft
9e10: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20  er opening.** a 
9e20: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
9e30: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
9e40: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73  at, unless it is
9e50: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72   rolled back for
9e60: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c   some.** reason,
9e70: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61   the entire data
9e80: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62  base file will b
9e90: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  e overwritten by
9ea0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
9eb0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
9ec0: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41  is is used by VA
9ed0: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e  CUUM operations.
9ee0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9ef0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
9f00: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
9f10: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
9f20: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
9f30: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
9f40: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20  the names of.** 
9f50: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74  all [VFSes] in t
9f60: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54  he VFS stack.  T
9f70: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20  he names are of 
9f80: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e  all VFS shims an
9f90: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62  d the.** final b
9fa0: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20  ottom-level VFS 
9fb0: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  are written into
9fc0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
9fd0: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
9fe0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
9ff0: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73   the result is s
a000: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61  tored in the cha
a010: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74  r* variable.** t
a020: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70  hat the fourth p
a030: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
a040: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
a050: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a  l()] points to..
a060: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73  ** The caller is
a070: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
a080: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d   freeing the mem
a090: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20  ory when done.  
a0a0: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66  As with.** all f
a0b0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69  ile-control acti
a0c0: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f  ons, there is no
a0d0: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
a0e0: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c  this will actual
a0f0: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e  ly.** do anythin
a100: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75  g.  Callers shou
a110: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68  ld initialize th
a120: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
a130: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   to a NULL.** po
a140: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68  inter in case th
a150: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
a160: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
a170: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63  ed.  This file-c
a180: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74  ontrol.** is int
a190: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f  ended for diagno
a1a0: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a  stic use only..*
a1b0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a1c0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d  E_FCNTL_PRAGMA]]
a1d0: 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20  .** ^Whenever a 
a1e0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
a1f0: 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e  nt is parsed, an
a200: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a210: 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20  RAGMA] .** file 
a220: 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20  control is sent 
a230: 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c  to the open [sql
a240: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
a250: 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  t corresponding.
a260: 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ** to the databa
a270: 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68  se file to which
a280: 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74   the pragma stat
a290: 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54  ement refers. ^T
a2a0: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
a2b0: 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  o the [SQLITE_FC
a2c0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a2d0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61   control is an a
a2e0: 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74  rray of.** point
a2f0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28  ers to strings (
a300: 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68  char**) in which
a310: 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d   the second elem
a320: 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79  ent of the array
a330: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
a340: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e  of the pragma an
a350: 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d  d the third elem
a360: 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ent is the argum
a370: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72  ent to the.** pr
a380: 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20  agma or NULL if 
a390: 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e  the pragma has n
a3a0: 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  o argument.  ^Th
a3b0: 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e  e handler for an
a3c0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
a3d0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a3e0: 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f  ontrol can optio
a3f0: 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66  nally make the f
a400: 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  irst element.** 
a410: 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72  of the char** ar
a420: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20  gument point to 
a430: 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  a string obtaine
a440: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
a450: 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72  mprintf()].** or
a460: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
a470: 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20  and that string 
a480: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
a490: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72  result of the pr
a4a0: 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65  agma or.** the e
a4b0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20  rror message if 
a4c0: 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73  the pragma fails
a4d0: 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51  . ^If the.** [SQ
a4e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a4f0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a500: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
a510: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20  NOTFOUND], then 
a520: 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47  normal .** [PRAG
a530: 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63  MA] processing c
a540: 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74  ontinues.  ^If t
a550: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a560: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
a570: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
a580: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
a590: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73  en the parser as
a5a0: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
a5b0: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65  * VFS has handle
a5c0: 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73  d the PRAGMA its
a5d0: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73  elf and the pars
a5e0: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e  er generates a n
a5f0: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64  o-op.** prepared
a600: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66   statement.  ^If
a610: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
a620: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a630: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a  control returns.
a640: 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f  ** any result co
a650: 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  de other than [S
a660: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51  QLITE_OK] or [SQ
a670: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
a680: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  that means.** th
a690: 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75  at the VFS encou
a6a0: 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20  ntered an error 
a6b0: 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74  while handling t
a6c0: 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20  he [PRAGMA] and 
a6d0: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69  the.** compilati
a6e0: 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41  on of the PRAGMA
a6f0: 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65   fails with an e
a700: 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c  rror.  ^The [SQL
a710: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a720: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
a730: 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20  l occurs at the 
a740: 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61  beginning of pra
a750: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  gma statement an
a760: 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a  alysis and so.**
a770: 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f   it is able to o
a780: 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e  verride built-in
a790: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
a7a0: 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ents..**.** <li>
a7b0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  [[SQLITE_FCNTL_B
a7c0: 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20  USYHANDLER]].** 
a7d0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a7e0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a  TL_BUSYHANDLER].
a7f0: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
a800: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62  may be invoked b
a810: 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20  y SQLite on the 
a820: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61  database file ha
a830: 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20  ndle.** shortly 
a840: 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e  after it is open
a850: 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70  ed in order to p
a860: 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20  rovide a custom 
a870: 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a  VFS with access.
a880: 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63  ** to the connec
a890: 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c  tions busy-handl
a8a0: 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65  er callback. The
a8b0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20   argument is of 
a8c0: 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a  type (void **).*
a8d0: 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20  * - an array of 
a8e0: 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c  two (void *) val
a8f0: 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28  ues. The first (
a900: 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79  void *) actually
a910: 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20   points.** to a 
a920: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
a930: 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a   (int (*)(void *
a940: 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  )). In order to 
a950: 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65  invoke the conne
a960: 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68  ctions.** busy-h
a970: 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e  andler, this fun
a980: 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20  ction should be 
a990: 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65  invoked with the
a9a0: 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29   second (void *)
a9b0: 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79   in.** the array
a9c0: 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67   as the only arg
a9d0: 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74  ument. If it ret
a9e0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
a9f0: 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f  hen the operatio
aa00: 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
aa10: 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65  etried. If it re
aa20: 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20  turns zero, the 
aa30: 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c  custom VFS shoul
aa40: 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a  d abandon the.**
aa50: 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69   current operati
aa60: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  on..**.** <li>[[
aa70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
aa80: 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  PFILENAME]].** ^
aa90: 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  Application can 
aaa0: 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49  invoke the [SQLI
aab0: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
aac0: 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74  ENAME] file-cont
aad0: 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53  rol.** to have S
aae0: 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61  QLite generate a
aaf0: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
ab00: 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65  lename using the
ab10: 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
ab20: 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64  that is followed
ab30: 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20   to generate.** 
ab40: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61  temporary filena
ab50: 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62  mes for TEMP tab
ab60: 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e  les and other in
ab70: 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68  ternal uses.  Th
ab80: 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  e.** argument sh
ab90: 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a  ould be a char**
aba0: 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66   which will be f
abb0: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66  illed with the f
abc0: 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74  ilename.** writt
abd0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
abe0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
abf0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
ac00: 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f    The caller sho
ac10: 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73  uld.** invoke [s
ac20: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
ac30: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20  n the result to 
ac40: 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c  avoid a memory l
ac50: 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  eak..**.** <li>[
ac60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
ac70: 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  AP_SIZE]].** The
ac80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
ac90: 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
aca0: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74  ontrol is used t
acb0: 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74  o query or set t
acc0: 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75  he.** maximum nu
acd0: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68  mber of bytes th
ace0: 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  at will be used 
acf0: 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65  for memory-mappe
ad00: 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72  d I/O..** The ar
ad10: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
ad20: 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f  ter to a value o
ad30: 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69  f type sqlite3_i
ad40: 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20  nt64 that.** is 
ad50: 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69  an advisory maxi
ad60: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
ad70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20  tes in the file 
ad80: 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20  to memory map.  
ad90: 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  The.** pointer i
ada0: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
adb0: 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65  th the old value
adc0: 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20  .  The limit is 
add0: 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a  not changed if.*
ade0: 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67  * the value orig
adf0: 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74  inally pointed t
ae00: 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61  o is negative, a
ae10: 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e  nd so the curren
ae20: 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20  t limit .** can 
ae30: 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61  be queried by pa
ae40: 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74  ssing in a point
ae50: 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65  er to a negative
ae60: 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a   number.  This.*
ae70: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  * file-control i
ae80: 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
ae90: 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  y to implement [
aea0: 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
aeb0: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ]..**.** </ul>.*
aec0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
aed0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
aee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
aef0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
af00: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
af10: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a  E             2.
af20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
af30: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
af40: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
af50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41  define SQLITE_LA
af60: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
af70: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#d
af80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
af90: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
afa0: 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
afb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
afc0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20  L_CHUNK_SIZE    
afd0: 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
afe0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
aff0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
b000: 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
b010: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b020: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
b030: 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e          8.#defin
b040: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
b050: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20  IN32_AV_RETRY   
b060: 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
b070: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45   SQLITE_FCNTL_PE
b080: 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20  RSIST_WAL       
b090: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
b0a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
b0b0: 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  RWRITE          
b0c0: 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53      11.#define S
b0d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
b0e0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20  AME             
b0f0: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51     12.#define SQ
b100: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
b110: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
b120: 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    13.#define SQL
b130: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b150: 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   14.#define SQLI
b160: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
b170: 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20  DLER            
b180: 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  15.#define SQLIT
b190: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
b1a0: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31  NAME           1
b1b0: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
b1c0: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
b1d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
b1e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b1f0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
b200: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
b210: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
b220: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
b230: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
b240: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
b250: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
b260: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
b270: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
b280: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
b290: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
b2a0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
b2b0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
b2c0: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
b2d0: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
b2e0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
b2f0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
b300: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
b310: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
b320: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
b330: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
b340: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
b350: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
b360: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
b370: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
b380: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
b390: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
b3a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
b3b0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
b3c0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
b3d0: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
b3e0: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
b3f0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
b400: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
b410: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
b420: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
b430: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
b440: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
b450: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
b460: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
b470: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
b480: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
b490: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
b4a0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
b4b0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
b4c0: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
b4d0: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
b4e0: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
b4f0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
b500: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
b510: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
b520: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
b530: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
b540: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
b550: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
b560: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
b570: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
b580: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
b590: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
b5a0: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
b5b0: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
b5c0: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
b5d0: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
b5e0: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
b5f0: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
b600: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
b610: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
b620: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
b630: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
b640: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
b650: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
b660: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
b670: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
b680: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
b690: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
b6a0: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
b6b0: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
b6c0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
b6d0: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
b6e0: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
b6f0: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
b700: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
b710: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
b720: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
b730: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
b740: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
b750: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
b760: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
b770: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
b780: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
b790: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
b7a0: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
b7b0: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
b7c0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
b7d0: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
b7e0: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
b7f0: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
b800: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
b810: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
b820: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
b830: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
b840: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
b850: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
b860: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
b870: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
b880: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
b890: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
b8a0: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
b8b0: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
b8c0: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
b8d0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
b8e0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
b8f0: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
b900: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
b910: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
b920: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
b930: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
b940: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
b950: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
b960: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
b970: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
b980: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
b990: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
b9a0: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
b9b0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
b9c0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
b9d0: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
b9e0: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
b9f0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
ba00: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
ba10: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
ba20: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
ba30: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
ba40: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
ba50: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
ba60: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
ba70: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
ba80: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
ba90: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
baa0: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
bab0: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
bac0: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
bad0: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
bae0: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
baf0: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
bb00: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
bb10: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
bb20: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
bb30: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
bb40: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
bb50: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
bb60: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
bb70: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
bb80: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
bb90: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
bba0: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
bbb0: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
bbc0: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
bbd0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
bbe0: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
bbf0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
bc00: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
bc10: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
bc20: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
bc30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
bc40: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
bc50: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
bc60: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
bc70: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
bc80: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
bc90: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
bca0: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
bcb0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
bcc0: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
bcd0: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
bce0: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
bcf0: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
bd00: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
bd10: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
bd20: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
bd30: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
bd40: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
bd50: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
bd60: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
bd70: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
bd80: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
bd90: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
bda0: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
bdb0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
bdc0: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
bdd0: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
bde0: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
bdf0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
be00: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
be10: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
be20: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
be30: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
be40: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
be50: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
be60: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
be70: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
be80: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
be90: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
bea0: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
beb0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
bec0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
bed0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
bee0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
bef0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
bf00: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
bf10: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
bf20: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
bf30: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
bf40: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
bf50: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
bf60: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
bf70: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
bf80: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
bf90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
bfa0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
bfb0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
bfc0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
bfd0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
bfe0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
bff0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c000: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
c010: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c020: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
c030: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
c040: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
c050: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
c060: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
c070: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
c080: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
c090: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
c0a0: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
c0b0: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
c0c0: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
c0d0: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
c0e0: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
c0f0: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
c100: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
c110: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
c120: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
c130: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
c140: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
c150: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
c160: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
c170: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
c180: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
c190: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
c1a0: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
c1b0: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
c1c0: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
c1d0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
c1e0: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
c1f0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
c200: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
c210: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
c220: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
c230: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
c240: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
c250: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
c260: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
c270: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
c280: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
c290: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
c2a0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
c2b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
c2c0: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
c2d0: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
c2e0: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
c2f0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
c300: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
c310: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
c320: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
c330: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
c340: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
c350: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
c360: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
c370: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
c380: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
c390: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
c3a0: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
c3b0: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
c3c0: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
c3d0: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
c3e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
c3f0: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
c400: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
c410: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
c420: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
c430: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
c440: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
c450: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
c460: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
c470: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
c480: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
c490: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
c4a0: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
c4b0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
c4c0: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
c4d0: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
c4e0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
c4f0: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
c500: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
c510: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
c520: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
c530: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
c540: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
c550: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
c560: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
c570: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
c580: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
c590: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
c5a0: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
c5b0: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
c5c0: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
c5d0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
c5e0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
c5f0: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
c600: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
c610: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
c620: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
c630: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
c640: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
c650: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
c660: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
c670: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
c680: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
c690: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
c6a0: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
c6b0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
c6c0: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
c6d0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
c6e0: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
c6f0: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
c700: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
c710: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
c720: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
c730: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
c740: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
c750: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
c760: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
c770: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
c780: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
c790: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
c7a0: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
c7b0: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
c7c0: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
c7d0: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
c7e0: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
c7f0: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
c800: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
c810: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
c820: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
c830: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
c840: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
c850: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
c860: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
c870: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
c880: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
c890: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
c8a0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
c8b0: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
c8c0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
c8d0: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
c8e0: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
c8f0: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
c900: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
c910: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
c920: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
c930: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
c940: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
c950: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
c960: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
c970: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
c980: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
c990: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
c9a0: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
c9b0: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
c9c0: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
c9d0: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
c9e0: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
c9f0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
ca00: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
ca10: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
ca20: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
ca30: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
ca40: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
ca50: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
ca60: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
ca70: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
ca80: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
ca90: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
caa0: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
cab0: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
cac0: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
cad0: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
cae0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
caf0: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
cb00: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
cb10: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
cb20: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
cb30: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
cb40: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
cb50: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
cb60: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
cb70: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
cb80: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
cb90: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
cba0: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
cbb0: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
cbc0: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
cbd0: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
cbe0: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
cbf0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
cc00: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
cc10: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
cc20: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
cc30: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
cc40: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
cc50: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
cc60: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
cc70: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
cc80: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
cc90: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
cca0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
ccb0: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
ccc0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
ccd0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
cce0: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
ccf0: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
cd00: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
cd10: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
cd20: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
cd30: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
cd40: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
cd50: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
cd60: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
cd70: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
cd80: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
cd90: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
cda0: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
cdb0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
cdc0: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
cdd0: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
cde0: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
cdf0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
ce00: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
ce10: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
ce20: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
ce30: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
ce40: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
ce50: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
ce60: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
ce70: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
ce80: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
ce90: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
cea0: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
ceb0: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
cec0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
ced0: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
cee0: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
cef0: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
cf00: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
cf10: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
cf20: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
cf30: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
cf40: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
cf50: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
cf60: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
cf70: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
cf80: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
cf90: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
cfa0: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
cfb0: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
cfc0: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
cfd0: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
cfe0: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
cff0: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
d000: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
d010: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
d020: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
d030: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
d040: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
d050: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
d060: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
d070: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
d080: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
d090: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
d0a0: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
d0b0: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
d0c0: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
d0d0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
d0e0: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
d0f0: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
d100: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
d110: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
d120: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
d130: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
d140: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
d150: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
d160: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
d170: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
d180: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
d190: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
d1a0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
d1b0: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
d1c0: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
d1d0: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
d1e0: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
d1f0: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
d200: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
d210: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
d220: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
d230: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
d240: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
d250: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
d260: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
d270: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
d280: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
d290: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
d2a0: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
d2b0: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
d2c0: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
d2d0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
d2e0: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
d2f0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
d300: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
d310: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
d320: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
d330: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
d340: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
d350: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
d360: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
d370: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
d380: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
d390: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
d3a0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
d3b0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
d3c0: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
d3d0: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
d3e0: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
d3f0: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
d400: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
d410: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
d420: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
d430: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
d440: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
d450: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
d460: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
d470: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
d480: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d490: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
d4a0: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
d4b0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
d4c0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d4d0: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
d4e0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
d4f0: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
d500: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
d510: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
d520: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
d530: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
d540: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
d550: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d560: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
d570: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
d580: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
d590: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
d5a0: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
d5b0: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
d5c0: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
d5d0: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
d5e0: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
d5f0: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
d600: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
d610: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
d620: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
d630: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
d640: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
d650: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
d660: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
d670: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
d680: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
d690: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
d6a0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
d6b0: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
d6c0: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
d6d0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d6e0: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
d6f0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
d700: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
d710: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
d720: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
d730: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
d740: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
d750: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
d760: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
d770: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
d780: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
d790: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
d7a0: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
d7b0: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
d7c0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
d7d0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
d7e0: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
d7f0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
d800: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
d810: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
d820: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
d830: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
d840: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
d850: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d860: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
d870: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
d880: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
d890: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
d8a0: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
d8b0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d8c0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
d8d0: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
d8e0: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
d8f0: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
d900: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d910: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
d920: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
d930: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
d940: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
d950: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
d960: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
d970: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
d980: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
d990: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
d9a0: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
d9b0: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
d9c0: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
d9d0: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
d9e0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
d9f0: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
da00: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
da10: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
da20: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
da30: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
da40: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
da50: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
da60: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
da70: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
da80: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
da90: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
daa0: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
dab0: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
dac0: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
dad0: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
dae0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
daf0: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
db00: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
db10: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
db20: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
db30: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
db40: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
db50: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
db60: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
db70: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
db80: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
db90: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
dba0: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
dbb0: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
dbc0: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
dbd0: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
dbe0: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
dbf0: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
dc00: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
dc10: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
dc20: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
dc30: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
dc40: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
dc50: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
dc60: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
dc70: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
dc80: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
dc90: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
dca0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
dcb0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
dcc0: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
dcd0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
dce0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
dcf0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
dd00: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
dd10: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
dd20: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
dd30: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
dd40: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
dd50: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
dd60: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
dd70: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
dd80: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
dd90: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
dda0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
ddb0: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
ddc0: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
ddd0: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
dde0: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
ddf0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
de00: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
de10: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
de20: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
de30: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
de40: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
de50: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
de60: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
de70: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
de80: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
de90: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
dea0: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
deb0: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
dec0: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
ded0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
dee0: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
def0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
df00: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
df10: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
df20: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
df30: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
df40: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
df50: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
df60: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
df70: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
df80: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
df90: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
dfa0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
dfb0: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
dfc0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
dfd0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
dfe0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
dff0: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
e000: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
e010: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
e020: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
e030: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
e040: 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74  * was given no t
e050: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
e060: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
e070: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
e080: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
e090: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
e0a0: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
e0b0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
e0c0: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
e0d0: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
e0e0: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
e0f0: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
e100: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
e110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
e120: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
e130: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
e140: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
e150: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
e160: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
e170: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
e180: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
e190: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
e1a0: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
e1b0: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
e1c0: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
e1d0: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
e1e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
e1f0: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
e200: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
e210: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
e220: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
e230: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
e240: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
e250: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
e260: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
e270: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
e280: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
e290: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
e2a0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
e2b0: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
e2c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
e2d0: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
e2e0: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
e2f0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
e300: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
e310: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
e320: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
e330: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
e340: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
e350: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
e360: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
e370: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
e380: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
e390: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e3a0: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
e3b0: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
e3c0: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
e3d0: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
e3e0: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
e3f0: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
e400: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
e410: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
e420: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
e430: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
e440: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
e450: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
e460: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
e470: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
e480: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
e490: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
e4a0: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
e4b0: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
e4c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e4d0: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
e4e0: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
e4f0: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
e500: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
e510: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
e520: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
e530: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
e540: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
e550: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
e560: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
e570: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
e580: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
e590: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e5a0: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
e5b0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
e5c0: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
e5d0: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
e5e0: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
e5f0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
e600: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
e610: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
e620: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
e630: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
e640: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e650: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
e660: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e670: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
e680: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
e690: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
e6a0: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
e6b0: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
e6c0: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
e6d0: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
e6e0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
e6f0: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
e700: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
e710: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
e720: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
e730: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
e740: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
e750: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
e760: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
e770: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
e780: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
e790: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
e7a0: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
e7b0: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
e7c0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e7d0: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
e7e0: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
e7f0: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
e800: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
e810: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
e820: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
e830: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e840: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
e850: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
e860: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e870: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
e880: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
e890: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
e8a0: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
e8b0: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
e8c0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
e8d0: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
e8e0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e8f0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
e900: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
e910: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
e920: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
e930: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
e940: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
e950: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
e960: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
e970: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
e980: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
e990: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
e9a0: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
e9b0: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
e9c0: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
e9d0: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
e9e0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
e9f0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
ea00: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
ea10: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
ea20: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
ea30: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
ea40: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
ea50: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
ea60: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
ea70: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
ea80: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
ea90: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
eaa0: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
eab0: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
eac0: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
ead0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
eae0: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
eaf0: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
eb00: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
eb10: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
eb20: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
eb30: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
eb40: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
eb50: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
eb60: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
eb70: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
eb80: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
eb90: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
eba0: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
ebb0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
ebc0: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
ebd0: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
ebe0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ebf0: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
ec00: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
ec10: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
ec20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ec30: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
ec40: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
ec50: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
ec60: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
ec70: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
ec80: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
ec90: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
eca0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
ecb0: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
ecc0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
ecd0: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
ece0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
ecf0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
ed00: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
ed10: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
ed20: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
ed30: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
ed40: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
ed50: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
ed60: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
ed70: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
ed80: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
ed90: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
eda0: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
edb0: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
edc0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
edd0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
ede0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
edf0: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
ee00: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
ee10: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
ee20: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
ee30: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
ee40: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
ee50: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
ee60: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
ee70: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
ee80: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
ee90: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
eea0: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
eeb0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
eec0: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
eed0: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
eee0: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
eef0: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
ef00: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
ef10: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
ef20: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
ef30: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
ef40: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
ef50: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
ef60: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
ef70: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
ef80: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
ef90: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
efa0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
efb0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
efc0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
efd0: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
efe0: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
eff0: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
f000: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
f010: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
f020: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
f030: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
f040: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
f050: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
f060: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
f070: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
f080: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
f090: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
f0a0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f0b0: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
f0c0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f0d0: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
f0e0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
f0f0: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
f100: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
f110: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
f120: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
f130: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
f140: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
f150: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
f160: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
f170: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
f180: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
f190: 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
f1a0: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
f1b0: 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
f1c0: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
f1d0: 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
f1e0: 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
f1f0: 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
f200: 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
f210: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
f220: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
f230: 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
f240: 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
f250: 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
f260: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
f270: 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
f280: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
f290: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
f2a0: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
f2b0: 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
f2c0: 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
f2d0: 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
f2e0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
f2f0: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
f300: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c  alize(void);.SQL
f310: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
f320: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
f330: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
f340: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
f350: 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  it(void);.SQLITE
f360: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
f370: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
f380: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f390: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
f3a0: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
f3b0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
f3c0: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
f3d0: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
f3e0: 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69  ake global confi
f3f0: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
f400: 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e  ges to SQLite in
f410: 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53   order to tune S
f420: 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65  QLite to the spe
f430: 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a  cific needs of.*
f440: 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
f450: 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  n.  The default 
f460: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73  configuration is
f470: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
f480: 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
f490: 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69  tions and so thi
f4a0: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75  s routine is usu
f4b0: 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61  ally not necessa
f4c0: 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72  ry.  It is.** pr
f4d0: 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72  ovided to suppor
f4e0: 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69  t rare applicati
f4f0: 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c  ons with unusual
f500: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   needs..**.** Th
f510: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
f520: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
f530: 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
f540: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
f550: 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20  .** must insure 
f560: 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
f570: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
f580: 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
f590: 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
f5a0: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
f5b0: 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
f5c0: 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c  g.  Furthermore,
f5d0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
f5e0: 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ).** may only be
f5f0: 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
f600: 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
f610: 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
f620: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
f630: 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
f640: 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
f650: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f660: 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
f670: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
f680: 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
f690: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f6a0: 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
f6b0: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
f6c0: 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
f6d0: 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
f6e0: 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
f6f0: 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
f700: 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
f710: 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
f720: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
f730: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
f740: 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
f750: 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
f760: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
f770: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
f780: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
f790: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
f7a0: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63  an integer.** [c
f7b0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
f7c0: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
f7d0: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
f7e0: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
f7f0: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
f800: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
f810: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
f820: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
f830: 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  the [configurati
f840: 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
f850: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
f860: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
f870: 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
f880: 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
f890: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f8a0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
f8b0: 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
f8c0: 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
f8d0: 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
f8e0: 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
f8f0: 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
f900: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
f910: 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
f920: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
f930: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
f940: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
f950: 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
f960: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
f970: 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
f980: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  onnections.**.**
f990: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
f9a0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
f9b0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
f9c0: 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ke configuration
f9d0: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61  .** changes to a
f9e0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
f9f0: 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74  ction].  The int
fa00: 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61  erface is simila
fa10: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
fa20: 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70  _config()] excep
fa30: 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67  t that the chang
fa40: 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69  es apply to a si
fa50: 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ngle.** [databas
fa60: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73  e connection] (s
fa70: 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
fa80: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e  first argument).
fa90: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
faa0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
fab0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
fac0: 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65  D,V,...)  is the
fad0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  .** [SQLITE_DBCO
fae0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c  NFIG_LOOKASIDE |
faf0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
fb00: 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65  erb] - an intege
fb10: 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20  r code .** that 
fb20: 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61  indicates what a
fb30: 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
fb40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
fb50: 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
fb60: 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65  igured..** Subse
fb70: 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20  quent arguments 
fb80: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
fb90: 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
fba0: 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  ion verb..**.** 
fbb0: 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
fbc0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65  3_db_config() re
fbd0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
fbe0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
fbf0: 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e   the call is con
fc00: 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66  sidered successf
fc10: 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
fc20: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62  I int sqlite3_db
fc30: 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
fc40: 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
fc50: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
fc60: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
fc70: 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
fc80: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
fc90: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
fca0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
fcb0: 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
fcc0: 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
fcd0: 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
fce0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
fcf0: 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
fd00: 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
fd10: 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
fd20: 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
fd30: 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
fd40: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
fd50: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
fd60: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
fd70: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
fd80: 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
fd90: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
fda0: 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
fdb0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
fdc0: 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
fdd0: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
fde0: 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
fdf0: 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
fe00: 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
fe10: 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
fe20: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
fe30: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
fe40: 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
fe50: 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
fe60: 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
fe70: 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
fe80: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
fe90: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fea0: 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
feb0: 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
fec0: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
fed0: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
fee0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
fef0: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
ff00: 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
ff10: 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
ff20: 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
ff30: 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
ff40: 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
ff50: 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
ff60: 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
ff70: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
ff80: 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
ff90: 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
ffa0: 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
ffb0: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
ffc0: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
ffd0: 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
ffe0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
fff0: 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
10000 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
10010 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
10020 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
10030 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
10040 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
10050 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
10060 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
10070 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
10080 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
10090 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
100a0 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
100b0 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
100c0 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
100d0 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
100e0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
100f0 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c  alloc, xRealloc,
10100 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
10110 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
10120 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
10130 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
10140 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e   free() function
10150 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
10160 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
10170 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
10180 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
10190 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
101a0 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
101b0 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
101c0 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
101d0 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
101e0 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  dup..**.** xSize
101f0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
10200 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
10210 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
10220 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
10230 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
10240 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
10250 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
10260 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
10270 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
10280 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
10290 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
102a0 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
102b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
102c0 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
102d0 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
102e0 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
102f0 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
10300 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10310 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
10320 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
10330 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
10340 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
10350 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
10360 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
10370 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
10380 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
10390 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
103a0 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
103b0 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
103c0 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
103d0 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
103e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
103f0 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
10400 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
10410 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
10420 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
10430 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
10440 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
10450 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
10460 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
10470 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
10480 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
10490 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
104a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
104b0 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
104c0 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
104d0 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72  allocator.  (For
104e0 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
104f0 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
10500 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
10510 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
10520 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
10530 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
10540 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
10550 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
10560 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
10570 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
10580 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
10590 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
105a0 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
105b0 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
105c0 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
105d0 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
105e0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
105f0 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
10600 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
10610 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
10620 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
10630 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
10640 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
10650 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
10660 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
10670 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
10680 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
10690 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
106a0 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
106b0 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
106c0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
106d0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
106e0 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
106f0 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
10700 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
10710 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
10720 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
10730 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
10740 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
10750 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
10760 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
10770 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
10780 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
10790 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
107a0 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
107b0 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
107c0 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
107d0 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
107e0 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
107f0 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
10800 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
10810 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
10820 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
10830 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
10840 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
10850 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
10860 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
10870 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
10880 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
10890 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
108a0 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
108b0 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
108c0 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
108d0 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
108e0 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
108f0 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
10900 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
10910 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
10920 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
10930 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
10940 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
10950 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
10960 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
10970 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
10980 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
10990 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
109a0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
109b0 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
109c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
109d0 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
109e0 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
109f0 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
10a00 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
10a10 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
10a20 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
10a30 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
10a40 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
10a50 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
10a60 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
10a70 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
10a80 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
10a90 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
10aa0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
10ab0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
10ac0 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
10ad0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
10ae0 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
10af0 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
10b00 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
10b10 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
10b20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
10b30 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
10b40 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
10b50 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
10b60 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
10b70 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
10b80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10b90 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
10ba0 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  Options.** KEYWO
10bb0 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74  RDS: {configurat
10bc0 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a  ion option}.**.*
10bd0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
10be0 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
10bf0 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
10c00 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10c10 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
10c20 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
10c30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
10c40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
10c50 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
10c60 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
10c70 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10c80 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
10c90 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
10ca0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
10cb0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
10cc0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
10cd0 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
10ce0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
10cf0 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
10d00 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
10d10 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
10d20 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
10d30 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
10d40 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
10d50 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
10d60 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
10d70 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
10d80 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
10d90 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
10da0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
10db0 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
10dc0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10dd0 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
10de0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
10df0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
10e00 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64  INGLETHREAD]] <d
10e10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10e20 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74  SINGLETHREAD</dt
10e30 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
10e40 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
10e50 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
10e60 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
10e70 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
10e80 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69  ding mode] to Si
10e90 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e  ngle-thread.  In
10ea0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
10eb0 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
10ec0 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
10ed0 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
10ee0 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
10ef0 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
10f00 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
10f10 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c  hread.   ^If SQL
10f20 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
10f30 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
10f40 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
10f50 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
10f60 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
10f70 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
10f80 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
10f90 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74  ible to change t
10fa0 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
10fb0 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66  de] from its def
10fc0 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  ault.** value of
10fd0 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61   Single-thread a
10fe0 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nd so [sqlite3_c
10ff0 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
11000 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  turn .** [SQLITE
11010 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
11020 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
11030 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
11040 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75  HREAD.** configu
11050 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
11060 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11070 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
11080 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
11090 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
110a0 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
110b0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
110c0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
110d0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
110e0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
110f0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
11100 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72  de] to Multi-thr
11110 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
11120 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
11130 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
11140 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11150 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
11160 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
11170 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
11180 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
11190 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
111a0 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
111b0 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
111c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
111d0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
111e0 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
111f0 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
11200 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
11210 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
11220 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
11230 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
11240 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
11250 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20  t as long as no 
11260 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65  two threads atte
11270 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73  mpt to use the s
11280 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ame.** [database
11290 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
112a0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20  the same time.  
112b0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
112c0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
112d0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
112e0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
112f0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
11300 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
11310 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
11320 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
11330 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72  et the Multi-thr
11340 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
11350 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
11360 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
11370 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
11380 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
11390 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
113a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
113b0 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67  LTITHREAD config
113c0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
113d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
113e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
113f0 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  LIZED]] <dt>SQLI
11400 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
11410 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
11420 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
11430 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
11440 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
11450 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
11460 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
11470 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64  e] to Serialized
11480 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
11490 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e  , this option en
114a0 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
114b0 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74  exes including t
114c0 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20  he recursive.** 
114d0 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61  mutexes on [data
114e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
114f0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
11500 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
11510 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f  s..** In this mo
11520 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65  de (which is the
11530 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51   default when SQ
11540 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11550 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45   with.** [SQLITE
11560 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20  _THREADSAFE=1]) 
11570 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
11580 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73  ry will itself s
11590 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a  erialize access.
115a0 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20  ** to [database 
115b0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
115c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
115d0 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74  ments] so that t
115e0 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  he.** applicatio
115f0 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65  n is free to use
11600 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
11610 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11620 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b  or the.** same [
11630 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11640 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74  nt] in different
11650 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
11660 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49  same time..** ^I
11670 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
11680 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
11690 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
116a0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
116b0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
116c0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
116d0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
116e0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
116f0 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20   the Serialized 
11700 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11710 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
11720 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
11730 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
11740 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
11750 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
11760 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
11770 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69  IZED configurati
11780 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
11790 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
117a0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c  ONFIG_MALLOC]] <
117b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
117c0 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
117d0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
117e0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
117f0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
11800 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
11810 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
11820 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
11830 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
11840 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
11850 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
11860 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
11870 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
11880 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
11890 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
118a0 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
118b0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
118c0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
118d0 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
118e0 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a  ^ ^SQLite makes.
118f0 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ** its own priva
11900 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63  te copy of the c
11910 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
11920 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11930 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ds] structure.**
11940 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c   before the [sql
11950 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63  ite3_config()] c
11960 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64  all returns.</dd
11970 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11980 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
11990 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
119a0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
119b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
119c0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
119d0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
119e0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
119f0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
11a00 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
11a10 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
11a20 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
11a30 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
11a40 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
11a50 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
11a60 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
11a70 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
11a80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11a90 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
11aa0 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
11ab0 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
11ac0 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65  d the default me
11ad0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
11ae0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
11af0 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20   a wrapper that 
11b00 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f  simulations memo
11b10 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
11b20 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63  ilure or.** trac
11b30 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c  ks memory usage,
11b40 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f   for example. </
11b50 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11b60 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
11b70 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TUS]] <dt>SQLITE
11b80 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
11b90 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  S</dt>.** <dd> ^
11ba0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
11bb0 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
11bc0 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69  t of type int, i
11bd0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
11be0 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  .** boolean, whi
11bf0 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
11c00 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
11c10 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20  ction of memory 
11c20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73  allocation .** s
11c30 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65  tatistics. ^(Whe
11c40 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
11c50 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
11c60 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  re disabled, the
11c70 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   .** following S
11c80 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
11c90 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
11ca0 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
11cb0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
11cc0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
11cd0 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
11ce0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
11cf0 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
11d00 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
11d10 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
11d20 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
11d30 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
11d40 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
11d50 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
11d60 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
11d70 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
11d80 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
11d90 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
11da0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
11db0 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
11dc0 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
11dd0 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
11de0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
11df0 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
11e00 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
11e10 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11e20 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
11e30 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  CH]] <dt>SQLITE_
11e40 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
11e50 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
11e60 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
11e70 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
11e80 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
11e90 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
11ea0 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  r.** scratch mem
11eb0 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20  ory.  There are 
11ec0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
11ed0 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38    A pointer an 8
11ee0 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
11ef0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66   memory buffer f
11f00 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63  rom which the sc
11f10 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
11f20 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61  s will be.** dra
11f30 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  wn, the size of 
11f40 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c  each scratch all
11f50 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a  ocation (sz),.**
11f60 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
11f70 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74   number of scrat
11f80 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28  ch allocations (
11f90 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61  N).  The sz.** a
11fa0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
11fb0 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36  a multiple of 16
11fc0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
11fd0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
11fe0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
11ff0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
12000 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
12010 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
12020 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
12030 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
12040 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20  o more than two 
12050 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
12060 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a  per thread.  So.
12070 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73  ** N should be s
12080 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20  et to twice the 
12090 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d  expected maximum
120a0 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61   number of threa
120b0 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ds..** ^SQLite w
120c0 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72  ill never requir
120d0 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  e a scratch buff
120e0 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
120f0 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20  than 6.** times 
12100 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
12110 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69  e size. ^If SQLi
12120 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61  te needs needs a
12130 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72  dditional.** scr
12140 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f  atch memory beyo
12150 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
12160 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66  ded by this conf
12170 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12180 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  , then .** [sqli
12190 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69  te3_malloc()] wi
121a0 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  ll be used to ob
121b0 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  tain the memory 
121c0 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  needed.</dd>.**.
121d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
121e0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c  IG_PAGECACHE]] <
121f0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12200 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
12210 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
12220 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
12230 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
12240 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
12250 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
12260 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
12270 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68  ge cache with th
12280 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63  e default page c
12290 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
122a0 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63  ion.  .** This c
122b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f  onfiguration sho
122c0 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
122d0 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
122e0 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a  n-define page.**
122f0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
12300 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20  ation is loaded 
12310 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  using the SQLITE
12320 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
12330 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65  option..** There
12340 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
12350 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
12360 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  ion: A pointer t
12370 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  o 8-byte aligned
12380 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20  .** memory, the 
12390 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
123a0 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61  e buffer (sz), a
123b0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
123c0 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   pages (N)..** T
123d0 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73  he sz argument s
123e0 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a  hould be the siz
123f0 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
12400 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a   database page.*
12410 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77  * (a power of tw
12420 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e  o between 512 an
12430 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20  d 32768) plus a 
12440 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72  little extra for
12450 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
12460 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65  ader.  ^The page
12470 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20   header size is 
12480 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64  20 to 40 bytes d
12490 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74  epending on.** t
124a0 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63  he host architec
124b0 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61  ture.  ^It is ha
124c0 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
124d0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
124e0 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65  mory,.** to make
124f0 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f   sz a little too
12500 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72   large.  The fir
12510 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  st.** argument s
12520 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61  hould point to a
12530 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20  n allocation of 
12540 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
12550 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
12560 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
12570 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
12580 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
12590 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
125a0 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
125b0 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
125c0 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
125d0 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
125e0 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64  o cache.  ^If ad
125f0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
12600 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
12610 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
12620 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
12630 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
12640 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
12650 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
12660 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
12670 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
12680 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54  rage space..** T
12690 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68  he pointer in th
126a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
126b0 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67   must.** be alig
126c0 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
126d0 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
126e0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
126f0 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69   of SQLite.** wi
12700 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
12710 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12720 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
12730 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12740 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a  NFIG_HEAP</dt>.*
12750 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
12760 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
12770 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
12780 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
12790 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72   will use.** for
127a0 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
127b0 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
127c0 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f  ation needs beyo
127d0 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65  nd those provide
127e0 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c  d.** for by [SQL
127f0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12800 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  CH] and [SQLITE_
12810 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
12820 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  ]..** There are 
12830 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
12840 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   An 8-byte align
12850 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ed pointer to th
12860 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65  e memory,.** the
12870 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
12880 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
12890 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
128a0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
128b0 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74  n size..** ^If t
128c0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
128d0 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
128e0 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
128f0 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
12900 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
12910 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
12920 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
12930 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
12940 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
12950 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
12960 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
12970 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
12980 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49  FIG_MALLOC].  ^I
12990 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  f the.** memory 
129a0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
129b0 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b  ULL and either [
129c0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
129d0 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51  MSYS3] or.** [SQ
129e0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
129f0 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64  YS5] are defined
12a00 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72  , then the alter
12a10 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a  native memory.**
12a20 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e   allocator is en
12a30 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20  gaged to handle 
12a40 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d  all of SQLites m
12a50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12a60 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66   needs..** The f
12a70 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
12a80 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
12a90 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  ) must be aligne
12aa0 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  d to an 8-byte.*
12ab0 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  * boundary or su
12ac0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
12ad0 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  r of SQLite will
12ae0 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   be undefined..*
12af0 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  * The minimum al
12b00 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73  location size is
12b10 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32   capped at 2**12
12b20 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c  . Reasonable val
12b30 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ues.** for the m
12b40 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
12b50 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20  n size are 2**5 
12b60 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64  through 2**8.</d
12b70 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12b80 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d  E_CONFIG_MUTEX]]
12b90 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12ba0 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
12bb0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
12bc0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
12bd0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
12be0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
12bf0 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
12c00 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12c10 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
12c20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
12c30 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
12c40 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
12c50 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65  e low-level mute
12c60 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  x routines to be
12c70 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a   used in place.*
12c80 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74  * the mutex rout
12c90 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
12ca0 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69  SQLite.)^  ^SQLi
12cb0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
12cc0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e  of the.** conten
12cd0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
12ce0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
12cf0 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72   structure befor
12d00 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  e the call to.**
12d10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12d20 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66  ()] returns. ^If
12d30 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12d40 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
12d50 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12d60 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
12d70 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
12d80 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
12d90 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
12da0 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
12db0 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
12dc0 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
12dd0 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
12de0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
12df0 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
12e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
12e10 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
12e20 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
12e30 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12e40 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
12e50 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12e60 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64  IG_GETMUTEX]] <d
12e70 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12e80 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  GETMUTEX</dt>.**
12e90 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
12ea0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
12eb0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
12ec0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
12ed0 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
12ee0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12ef0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
12f00 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
12f10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
12f20 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
12f30 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
12f40 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
12f50 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
12f60 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
12f70 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
12f80 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
12f90 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
12fa0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
12fb0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
12fc0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
12fd0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
12fe0 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
12ff0 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
13000 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
13010 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
13020 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13030 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13040 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
13050 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
13060 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
13070 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13080 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
13090 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
130a0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
130b0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
130c0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
130d0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
130e0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
130f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13100 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
13110 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
13120 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
13130 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
13140 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13150 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
13160 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
13170 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13180 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13190 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
131a0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
131b0 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
131c0 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65  he default.** me
131d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
131e0 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  for the lookasid
131f0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
13200 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64  or on each.** [d
13210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13220 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  on].  The first 
13230 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
13240 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
13250 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
13260 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65   slot and the se
13270 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62  cond is the numb
13280 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61  er of.** slots a
13290 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68  llocated to each
132a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
132b0 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20  tion.)^  ^(This 
132c0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
132d0 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69  ** <i>default</i
132e0 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65  > lookaside size
132f0 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42  . The [SQLITE_DB
13300 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13310 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71  ].** verb to [sq
13320 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
13330 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
13340 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
13350 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
13360 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
13370 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
13380 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s.)^ </dd>.**.**
13390 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
133a0 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  _PCACHE2]] <dt>S
133b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
133c0 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
133d0 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
133e0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
133f0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
13400 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
13410 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
13420 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
13430 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
13440 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  ct specifies the
13450 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f   interface.** to
13460 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
13470 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
13480 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ion.)^  ^SQLite 
13490 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
134a0 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e  the.** object an
134b0 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61  d uses it for pa
134c0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
134d0 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64  allocations.</dd
134e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
134f0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
13500 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
13510 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
13520 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
13530 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
13540 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13550 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
13560 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
13570 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
13580 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
13590 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
135a0 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  s of the current
135b0 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69  .** page cache i
135c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
135d0 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
135e0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
135f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13600 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
13610 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
13620 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
13630 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
13640 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
13650 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
13660 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
13670 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
13680 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13690 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
136a0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
136b0 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
136c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
136d0 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
136e0 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
136f0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
13700 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
13710 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
13720 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
13730 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
13740 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
13750 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
13760 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
13770 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
13780 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
13790 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
137a0 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
137b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
137c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
137d0 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
137e0 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
137f0 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
13800 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
13810 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
13820 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
13830 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
13840 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13850 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
13860 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
13870 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
13880 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
13890 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
138a0 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
138b0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
138c0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
138d0 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
138e0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
138f0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
13900 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
13910 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
13920 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
13930 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
13940 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
13950 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
13960 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
13970 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
13980 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
13990 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
139a0 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
139b0 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
139c0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
139d0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
139e0 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
139f0 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
13a00 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
13a10 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
13a20 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
13a30 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
13a40 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
13a50 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
13a60 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
13a70 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
13a80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
13a90 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
13aa0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
13ab0 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
13ac0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13ad0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
13ae0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13af0 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68  G_URI.** <dd> Th
13b00 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
13b10 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13b20 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49  t of type int. I
13b30 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
13b40 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  .** URI handling
13b50 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
13b60 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72  bled. If the par
13b70 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20  ameter is zero, 
13b80 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
13b90 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79  g.** is globally
13ba0 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52   disabled. If UR
13bb0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
13bc0 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20  obally enabled, 
13bd0 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a  all filenames.**
13be0 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
13bf0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
13c00 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
13c10 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
13c20 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
13c30 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
13c40 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
13c50 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
13c60 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
13c70 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
13c80 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
13c90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
13ca0 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
13cb0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
13cc0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
13cd0 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73  opened. If it is
13ce0 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
13cf0 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  ed, filenames ar
13d00 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70  e.** only interp
13d10 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66  reted as URIs if
13d20 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
13d30 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74  _URI flag is set
13d40 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74   when the.** dat
13d50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13d60 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64   is opened. By d
13d70 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64  efault, URI hand
13d80 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
13d90 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68  .** disabled. Th
13da0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
13db0 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62  may be changed b
13dc0 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68  y compiling with
13dd0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
13de0 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20  USE_URI] symbol 
13df0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b  defined..**.** [
13e00 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  [SQLITE_CONFIG_C
13e10 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
13e20 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AN]] <dt>SQLITE_
13e30 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
13e40 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64  INDEX_SCAN.** <d
13e50 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  d> This option t
13e60 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
13e70 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77  teger argument w
13e80 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65  hich is interpre
13e90 74 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c  ted as.** a bool
13ea0 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
13eb0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
13ec0 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
13ed0 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
13ee0 72 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20  r.** full table 
13ef0 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
13f00 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54  ry optimizer.  T
13f10 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
13f20 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
13f30 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
13f40 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
13f50 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
13f60 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
13f70 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
13f80 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
13f90 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
13fa0 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
13fb0 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
13fc0 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
13fd0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
13fe0 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
13ff0 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
14000 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
14010 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
14020 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
14030 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
14040 2a 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68  * malfunction wh
14050 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  en the optimizat
14060 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20  ion is enabled. 
14070 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61   Providing the a
14080 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73  bility to.** dis
14090 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a  able the optimiz
140a0 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65  ation allows the
140b0 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70   older, buggy ap
140c0 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74  plication code t
140d0 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75  o work.** withou
140e0 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69  t change even wi
140f0 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  th newer version
14100 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
14110 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14120 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51  IG_PCACHE]] [[SQ
14130 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14140 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  CACHE]].** <dt>S
14150 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14160 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43  CHE and SQLITE_C
14170 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a  ONFIG_GETPCACHE.
14180 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70  ** <dd> These op
14190 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65  tions are obsole
141a0 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  te and should no
141b0 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77  t be used by new
141c0 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61   code..** They a
141d0 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
141e0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
141f0 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20  ibility but are 
14200 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c  now no-ops..** <
14210 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14220 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
14230 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  G]].** <dt>SQLIT
14240 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a  E_CONFIG_SQLLOG.
14250 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
14260 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
14270 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69  able if sqlite i
14280 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
14290 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
142a0 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72  NABLE_SQLLOG] pr
142b0 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  e-processor macr
142c0 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66  o defined. The f
142d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68  irst argument sh
142e0 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69  ould.** be a poi
142f0 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69  nter to a functi
14300 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28  on of type void(
14310 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
14320 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  *,const char*, i
14330 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  nt)..** The seco
14340 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20  nd should be of 
14350 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68  type (void*). Th
14360 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
14370 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62  voked by the lib
14380 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65  rary.** in three
14390 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d   separate circum
143a0 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66  stances, identif
143b0 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65  ied by the value
143c0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a   passed as the.*
143d0 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
143e0 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74  er. If the fourt
143f0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30  h parameter is 0
14400 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
14410 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
14420 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
14430 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
14440 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70  has just been op
14450 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20  ened. The third 
14460 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e  argument.** poin
14470 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63  ts to a buffer c
14480 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61  ontaining the na
14490 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64  me of the main d
144a0 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66  atabase file. If
144b0 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
144c0 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74  arameter is 1, t
144d0 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
144e0 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74  ement that the t
144f0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  hird parameter.*
14500 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20  * points to has 
14510 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74  just been execut
14520 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66  ed. Or, if the f
14530 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
14540 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  is 2, then.** th
14550 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69  e connection bei
14560 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ng passed as the
14570 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
14580 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65  r is being close
14590 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  d. The.** third 
145a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73  parameter is pas
145b0 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73  sed NULL In this
145c0 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70   case.  An examp
145d0 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  le of using this
145e0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
145f0 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  n option can be 
14600 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73  seen in the "tes
14610 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72  t_sqllog.c" sour
14620 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68  ce file in.** th
14630 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69  e canonical SQLi
14640 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c  te source tree.<
14650 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14660 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
14670 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
14680 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
14690 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 53 51 4c  _SIZE.** <dd>SQL
146a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
146b0 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36  SIZE takes two 6
146c0 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73  4-bit integer (s
146d0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61  qlite3_int64) va
146e0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  lues.** that are
146f0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61   the default mma
14700 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68  p size limit (th
14710 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
14720 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41  g for.** [PRAGMA
14730 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64   mmap_size]) and
14740 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c   the maximum all
14750 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c  owed mmap size l
14760 69 6d 69 74 2e 0a 2a 2a 20 54 68 65 20 64 65 66  imit..** The def
14770 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e  ault setting can
14780 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62   be overridden b
14790 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  y each database 
147a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67  connection using
147b0 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b  .** either the [
147c0 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
147d0 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79  ] command, or by
147e0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53   using the.** [S
147f0 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
14800 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74  _SIZE] file cont
14810 72 6f 6c 2e 20 20 54 68 65 20 6d 61 78 69 6d 75  rol.  The maximu
14820 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
14830 69 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65  ize.** cannot be
14840 20 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d   changed at run-
14850 74 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74  time.  Nor may t
14860 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
14870 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
14880 65 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69  exceed the compi
14890 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
148a0 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
148b0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
148c0 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
148d0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
148e0 6f 6e 2e 20 20 0a 2a 2a 20 49 66 20 65 69 74 68  on.  .** If eith
148f0 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
14900 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
14910 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
14920 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
14930 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
14940 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
14950 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  ault..** </dl>.*
14960 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14970 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
14980 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
14990 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
149a0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
149b0 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
149c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
149d0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
149e0 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
149f0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
14a00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
14a10 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
14a20 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
14a30 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
14a40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14a50 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
14a60 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
14a70 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
14a80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
14a90 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
14aa0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
14ab0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
14ac0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14ad0 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
14ae0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
14af0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
14b00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14b10 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
14b20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
14b30 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
14b40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14b50 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
14b60 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
14b70 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
14b80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
14b90 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
14ba0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
14bb0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
14bc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14bd0 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
14be0 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
14bf0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
14c00 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
14c10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
14c20 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
14c30 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
14c40 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
14c50 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14c60 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
14c70 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
14c80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
14c90 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
14ca0 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
14cb0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14cc0 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
14cd0 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
14ce0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14cf0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
14d00 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
14d10 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
14d20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
14d30 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
14d40 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
14d50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14d60 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
14d70 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
14d80 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
14d90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14da0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
14db0 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
14dc0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14dd0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
14de0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
14df0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
14e00 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
14e10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14e20 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
14e30 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
14e40 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
14e50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14e60 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
14e70 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
14e80 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
14e90 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
14ea0 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
14eb0 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
14ec0 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
14ed0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
14ee0 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
14ef0 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
14f00 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14f10 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
14f20 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
14f30 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
14f40 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
14f50 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
14f60 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
14f70 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
14f80 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
14f90 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
14fa0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
14fb0 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
14fc0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14fd0 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
14fe0 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
14ff0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
15000 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
15010 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
15020 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
15030 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
15040 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
15050 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
15060 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
15070 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
15080 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
15090 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
150a0 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
150b0 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
150c0 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
150d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
150e0 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
150f0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
15100 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
15110 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
15120 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
15130 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
15140 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
15150 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
15160 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
15170 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
15180 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
15190 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
151a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
151b0 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
151c0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
151d0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
151e0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
151f0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
15200 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
15210 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
15220 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
15230 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
15240 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15250 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
15260 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
15270 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
15280 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
15290 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
152a0 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
152b0 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
152c0 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
152d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
152e0 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
152f0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
15300 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
15310 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
15320 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
15330 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
15340 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
15350 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
15360 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
15370 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
15380 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
15390 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
153a0 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
153b0 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
153c0 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
153d0 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
153e0 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
153f0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
15400 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
15410 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
15420 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
15430 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
15440 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
15450 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
15460 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
15470 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
15480 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
15490 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
154a0 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
154b0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
154c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
154d0 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
154e0 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
154f0 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
15500 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
15510 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
15520 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
15530 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
15540 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
15550 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
15560 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
15570 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
15580 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
15590 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
155a0 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
155b0 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
155c0 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
155d0 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
155e0 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
155f0 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
15600 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
15610 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
15620 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
15630 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
15640 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
15650 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
15660 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
15670 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
15680 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
15690 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
156a0 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
156b0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
156c0 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
156d0 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
156e0 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
156f0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
15700 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
15710 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
15720 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
15730 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
15740 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
15750 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
15760 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
15770 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
15780 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
15790 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
157a0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
157b0 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
157c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
157d0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
157e0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
157f0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
15800 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
15810 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
15820 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
15830 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
15840 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
15850 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
15860 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
15870 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
15880 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
15890 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
158a0 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
158b0 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
158c0 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
158d0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
158e0 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
158f0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
15900 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
15910 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
15920 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
15930 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
15940 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
15950 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
15960 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
15970 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
15980 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
15990 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
159a0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
159b0 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
159c0 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
159d0 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
159e0 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
159f0 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
15a00 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
15a10 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
15a20 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
15a30 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
15a40 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
15a50 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
15a60 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
15a70 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
15a80 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
15a90 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
15aa0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
15ab0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
15ac0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
15ad0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
15ae0 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
15af0 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
15b00 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
15b10 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
15b20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
15b30 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
15b40 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20         1001  /* 
15b50 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
15b60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15b70 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
15b80 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f  FKEY     1002  /
15b90 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
15ba0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
15bb0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
15bc0 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69  GGER  1003  /* i
15bd0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
15be0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
15bf0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
15c00 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
15c10 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  odes.**.** ^The 
15c20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
15c30 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
15c40 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
15c50 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
15c60 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
15c70 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
15c80 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
15c90 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
15ca0 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
15cb0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
15cc0 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
15cd0 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
15ce0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
15cf0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
15d00 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
15d10 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
15d20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
15d30 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
15d40 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
15d50 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
15d60 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
15d70 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
15d80 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
15d90 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
15da0 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
15db0 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
15dc0 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
15dd0 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
15de0 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
15df0 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
15e00 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
15e10 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
15e20 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
15e30 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
15e40 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
15e50 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
15e60 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
15e70 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
15e80 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
15e90 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
15ea0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
15eb0 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
15ec0 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
15ed0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
15ee0 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
15ef0 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  d] of the most r
15f00 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
15f10 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
15f20 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
15f30 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
15f40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
15f50 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
15f60 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20  gument.  ^As of 
15f70 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
15f80 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69  .7.7, this routi
15f90 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74  nes.** records t
15fa0 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72  he last insert r
15fb0 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64  owid of both ord
15fc0 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64  inary tables and
15fd0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
15fe0 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63  ]..** ^If no suc
15ff0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
16000 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
16010 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20  ccurred on that 
16020 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16030 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74  ion, zero is ret
16040 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  urned..**.** ^(I
16050 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
16060 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
16070 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20  igger or within 
16080 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
16090 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65  ].** method, the
160a0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
160b0 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b  ill return the [
160c0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
160d0 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73  serted.** row as
160e0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
160f0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
16100 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20  table method is 
16110 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
16120 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
16130 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
16140 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74  e method ends, t
16150 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
16160 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
16170 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
16180 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
16190 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
161a0 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  or virtual.** ta
161b0 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e  ble method began
161c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
161d0 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
161e0 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
161f0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
16200 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
16210 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
16220 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
16230 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
16240 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
16250 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
16260 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
16270 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
16280 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
16290 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
162a0 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
162b0 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
162c0 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
162d0 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
162e0 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
162f0 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
16300 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
16310 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
16320 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
16330 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
16340 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
16350 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
16360 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
16370 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
16380 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
16390 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
163a0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
163b0 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
163c0 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
163d0 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
163e0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
163f0 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
16400 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
16410 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
16420 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
16430 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
16440 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
16450 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
16460 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
16470 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
16480 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
16490 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
164a0 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
164b0 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
164c0 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
164d0 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
164e0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
164f0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
16500 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
16510 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
16520 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
16530 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
16540 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
16550 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
16560 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
16570 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
16580 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
16590 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
165a0 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
165b0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
165c0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
165d0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
165e0 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
165f0 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
16600 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
16610 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
16620 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
16630 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
16640 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
16650 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
16660 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
16670 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
16680 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
16690 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
166a0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
166b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
166c0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
166d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
166e0 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
166f0 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f  ere changed.** o
16700 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
16710 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
16720 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
16730 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  eted SQL stateme
16740 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61  nt.** on the [da
16750 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16760 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20  n] specified by 
16770 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
16780 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63  ter..** ^(Only c
16790 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20  hanges that are 
167a0 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69  directly specifi
167b0 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52  ed by the [INSER
167c0 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a  T], [UPDATE],.**
167d0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
167e0 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74  tement are count
167f0 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63  ed.  Auxiliary c
16800 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
16810 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20  .** triggers or 
16820 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
16830 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  ions] are not co
16840 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65  unted.)^ Use the
16850 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  .** [sqlite3_tot
16860 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
16870 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74  nction to find t
16880 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
16890 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e  of changes.** in
168a0 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20  cluding changes 
168b0 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65  caused by trigge
168c0 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b  rs and foreign k
168d0 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  ey actions..**.*
168e0 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  * ^Changes to a 
168f0 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69  view that are si
16900 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49  mulated by an [I
16910 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
16920 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  r].** are not co
16930 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61  unted.  Only rea
16940 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20  l table changes 
16950 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
16960 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e  ** ^(A "row chan
16970 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
16980 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
16990 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
169a0 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
169b0 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
169c0 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
169d0 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
169e0 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
169f0 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
16a00 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   of [REPLACE] co
16a10 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
16a20 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b  ion,.** rollback
16a30 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  , ABORT processi
16a40 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d  ng, [DROP TABLE]
16a50 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65  , or by any othe
16a60 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20  r.** mechanisms 
16a70 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
16a80 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
16a90 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  es.)^.**.** A "t
16aa0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
16ab0 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
16ac0 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
16ad0 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
16ae0 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
16af0 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49  of a [CREATE TRI
16b00 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e  GGER | trigger].
16b10 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74   .** Most SQL st
16b20 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
16b30 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64  evaluated outsid
16b40 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72  e of any trigger
16b50 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22  .  This is the "
16b60 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72  top level".** tr
16b70 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20  igger context.  
16b80 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72  If a trigger fir
16b90 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  es from the top 
16ba0 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20  level, a.** new 
16bb0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20  trigger context 
16bc0 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74  is entered for t
16bd0 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74  he duration of t
16be0 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67  hat one.** trigg
16bf0 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73  er.  Subtriggers
16c00 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65   create subconte
16c10 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75  xts for their du
16c20 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ration..**.** ^C
16c30 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
16c40 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
16c50 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
16c60 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
16c70 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
16c80 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
16c90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  ..**.** ^This fu
16ca0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
16cb0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72  he number of dir
16cc0 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  ect row changes 
16cd0 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  in the.** most r
16ce0 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
16cf0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
16d00 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
16d10 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69   the same.** tri
16d20 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
16d30 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20  .** ^Thus, when 
16d40 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
16d50 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20  top level, this 
16d60 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
16d70 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
16d80 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  f changes in the
16d90 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
16da0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
16db0 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61  DELETE.** that a
16dc0 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20  lso occurred at 
16dd0 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20  the top level.  
16de0 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64  ^(Within the bod
16df0 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a  y of a trigger,.
16e00 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ** the sqlite3_c
16e10 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61  hanges() interfa
16e20 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ce can be called
16e30 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
16e40 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65  ber of.** change
16e50 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
16e60 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
16e70 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
16e80 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
16e90 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
16ea0 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73  he body of the s
16eb0 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20  ame trigger..** 
16ec0 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d  However, the num
16ed0 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65  ber returned doe
16ee0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
16ef0 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20  anges.** caused 
16f00 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73  by subtriggers s
16f10 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20  ince those have 
16f20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78  their own contex
16f30 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
16f40 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
16f50 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
16f60 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
16f70 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
16f80 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
16f90 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
16fa0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
16fb0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
16fc0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
16fd0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
16fe0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
16ff0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
17000 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
17010 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
17020 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
17030 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
17040 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
17050 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
17060 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
17070 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
17080 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
17090 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
170a0 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
170b0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
170c0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
170d0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
170e0 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
170f0 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53  s caused by [INS
17100 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45  ERT],.** [UPDATE
17110 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
17120 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74  atements since t
17130 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
17140 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65  nection] was ope
17150 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f  ned..** ^(The co
17160 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  unt returned by 
17170 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
17180 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73  anges() includes
17190 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20   all changes.** 
171a0 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45  from all [CREATE
171b0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
171c0 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64  er] contexts and
171d0 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79   changes made by
171e0 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
171f0 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76   actions]. Howev
17200 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
17210 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
17220 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
17230 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50  o implement [REP
17240 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
17250 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
17260 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
17270 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50  essing, or [DROP
17280 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69   TABLE] processi
17290 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e  ng.  The.** coun
172a0 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
172b0 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73  de rows of views
172c0 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49   that fire an [I
172d0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
172e0 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66  r],.** though if
172f0 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20   the INSTEAD OF 
17300 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68  trigger makes ch
17310 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e  anges of its own
17320 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  , those changes 
17330 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  .** are counted.
17340 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  )^.** ^The sqlit
17350 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
17360 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e  () function coun
17370 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  ts the changes a
17380 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65  s soon as.** the
17390 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
173a0 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
173b0 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
173c0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
173d0 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  le.** is passed 
173e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
173f0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
17400 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
17410 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
17420 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
17430 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
17440 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
17450 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
17460 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
17470 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
17480 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
17490 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
174a0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
174b0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
174c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
174d0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
174e0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
174f0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
17500 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
17510 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
17520 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
17530 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
17540 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
17550 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
17560 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
17570 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17580 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
17590 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
175a0 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  y.**.** ^This fu
175b0 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
175c0 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
175d0 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
175e0 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
175f0 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
17600 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
17610 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
17620 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
17630 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
17640 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
17650 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
17660 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
17670 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
17680 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
17690 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
176a0 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
176b0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
176c0 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74  ** ^It is safe t
176d0 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
176e0 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
176f0 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
17700 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
17710 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
17720 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
17730 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
17740 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
17750 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
17760 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
17770 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
17780 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
17790 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
177a0 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
177b0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
177c0 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
177d0 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20  *.** ^If an SQL 
177e0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72  operation is ver
177f0 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
17800 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
17810 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  en.** sqlite3_in
17820 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c  terrupt() is cal
17830 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
17840 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
17850 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f  pportunity.** to
17860 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20   be interrupted 
17870 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e  and might contin
17880 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
17890 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20  ..**.** ^An SQL 
178a0 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
178b0 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
178c0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
178d0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
178e0 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75   ^If the interru
178f0 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
17900 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c  on is an INSERT,
17910 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
17920 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  TE.** that is in
17930 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
17940 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
17950 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
17960 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c  ansaction.** wil
17970 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
17980 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
17990 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
179a0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
179b0 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63  call is in effec
179c0 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72  t until all curr
179d0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a  ently running.**
179e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
179f0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
17a00 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c  nection] D compl
17a10 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53  ete.  ^Any new S
17a20 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
17a30 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
17a40 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
17a50 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
17a60 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20  call and before 
17a70 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  the .** running 
17a80 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68  statements reach
17a90 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65  es zero are inte
17aa0 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68  rrupted as if th
17ab0 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72  ey had been.** r
17ac0 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20  unning prior to 
17ad0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
17ae0 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e  rrupt() call.  ^
17af0 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  New SQL statemen
17b00 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
17b10 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
17b20 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
17b30 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73  nt count reaches
17b40 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74   zero are.** not
17b50 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65   effected by the
17b60 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
17b70 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  pt()..** ^A call
17b80 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   to sqlite3_inte
17b90 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63  rrupt(D) that oc
17ba0 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20  curs when there 
17bb0 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a  are no running.*
17bc0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
17bd0 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20   is a no-op and 
17be0 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
17bf0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
17c00 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
17c10 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
17c20 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
17c30 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a  ) call returns..
17c40 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  **.** If the dat
17c50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17c60 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73   closes while [s
17c70 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
17c80 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e  ()].** is runnin
17c90 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67  g then bad thing
17ca0 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61  s will likely ha
17cb0 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ppen..*/.SQLITE_
17cc0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
17cd0 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
17ce0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
17cf0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
17d00 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
17d10 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
17d20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
17d30 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
17d40 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
17d50 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
17d60 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
17d70 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
17d80 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
17d90 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
17da0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
17db0 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
17dc0 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
17dd0 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
17de0 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
17df0 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
17e00 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
17e10 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
17e20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
17e30 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
17e40 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
17e50 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
17e60 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
17e70 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
17e80 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
17e90 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
17ea0 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
17eb0 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
17ec0 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
17ed0 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
17ee0 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
17ef0 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
17f00 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
17f10 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
17f20 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
17f30 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
17f40 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
17f50 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
17f60 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
17f70 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
17f80 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
17f90 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
17fa0 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
17fb0 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
17fc0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
17fd0 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
17fe0 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
17ff0 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
18000 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
18010 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
18020 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
18030 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
18040 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
18050 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
18060 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
18070 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
18080 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
18090 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
180a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
180b0 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
180c0 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
180d0 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
180e0 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
180f0 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
18100 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
18110 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
18120 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
18130 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
18140 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
18150 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
18160 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
18170 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
18180 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
18190 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
181a0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
181b0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
181c0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
181d0 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
181e0 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
181f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
18200 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
18210 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
18220 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
18230 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
18240 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
18250 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
18260 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
18270 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
18280 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
18290 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
182a0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
182b0 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
182c0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
182d0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
182e0 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
182f0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
18300 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
18310 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
18320 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
18330 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
18340 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
18350 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
18360 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
18370 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
18380 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
18390 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
183a0 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
183b0 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
183c0 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
183d0 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20  SY Errors.**.** 
183e0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
183f0 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
18400 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68  nction that migh
18410 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  t be invoked whe
18420 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
18430 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
18440 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74  pen a database t
18450 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65  able that anothe
18460 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
18470 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
18480 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
18490 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
184a0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
184b0 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
184c0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
184d0 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  KED].** is retur
184e0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
184f0 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
18500 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66  g the lock.  ^If
18510 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
18520 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
18530 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
18540 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e  back might be in
18550 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
18560 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
18570 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
18580 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
18590 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70  handler is a cop
185a0 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
185b0 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ointer which.** 
185c0 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  is the third arg
185d0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
185e0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e  _busy_handler().
185f0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72    ^The second ar
18600 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
18610 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
18620 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
18630 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
18640 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
18650 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
18660 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73  invoked for this
18670 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
18680 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79   ^If the.** busy
18690 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
186a0 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64  s 0, then no add
186b0 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73  itional attempts
186c0 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20   are made to.** 
186d0 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
186e0 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ase and [SQLITE_
186f0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
18700 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
18710 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
18720 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
18730 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
18740 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
18750 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
18760 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  de to open the d
18770 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
18780 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
18790 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
187a0 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
187b0 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
187c0 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
187d0 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
187e0 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
187f0 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
18800 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66   contention. ^If
18810 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
18820 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
18830 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
18840 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
18850 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
18860 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
18870 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
18880 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72  LITE_BUSY].** or
18890 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
188a0 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20  LOCKED] instead 
188b0 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
188c0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
188d0 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
188e0 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
188f0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
18900 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
18910 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
18920 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
18930 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
18940 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
18950 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
18960 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
18970 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
18980 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
18990 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
189a0 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
189b0 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
189c0 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
189d0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
189e0 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
189f0 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
18a00 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
18a10 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
18a20 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
18a30 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
18a40 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
18a50 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
18a60 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
18a70 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
18a80 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
18a90 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
18aa0 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
18ab0 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
18ac0 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
18ad0 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
18ae0 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
18af0 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
18b00 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
18b10 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
18b20 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
18b30 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
18b40 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
18b50 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
18b60 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
18b70 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  LL..**.** ^The [
18b80 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
18b90 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
18ba0 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
18bb0 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
18bc0 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
18bd0 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
18be0 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
18bf0 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
18c00 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
18c10 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
18c20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
18c30 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
18c40 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
18c50 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
18c60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
18c70 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
18c80 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
18c90 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
18ca0 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
18cb0 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
18cc0 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
18cd0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
18ce0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
18cf0 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
18d00 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20  eaders.  ^If it 
18d10 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f  is unable to pro
18d20 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74  mote the lock, t
18d30 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  hen the in-memor
18d40 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20  y.** cache will 
18d50 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e  be left in an in
18d60 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65  consistent state
18d70 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f   and so the erro
18d80 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f  r.** code is pro
18d90 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72  moted from the r
18da0 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e  elatively benign
18db0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74   [SQLITE_BUSY] t
18dc0 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65  o.** the more se
18dd0 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45  vere [SQLITE_IOE
18de0 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54  RR_BLOCKED].  ^T
18df0 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70  his error code p
18e00 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63  romotion.** forc
18e10 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  es an automatic 
18e20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  rollback of the 
18e30 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68  changes.  See th
18e40 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63  e.** <a href="/c
18e50 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f  vstrac/wiki?p=Co
18e60 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
18e70 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20  gBusyError">.** 
18e80 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
18e90 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e  ingBusyError</a>
18ea0 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61   wiki page for a
18eb0 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77   discussion of w
18ec0 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d  hy.** this is im
18ed0 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  portant..**.** ^
18ee0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
18ef0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
18f00 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
18f10 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
18f20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18f30 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
18f40 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
18f50 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
18f60 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
18f70 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
18f80 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
18f90 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
18fa0 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73  t()].** will als
18fb0 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74  o set or clear t
18fc0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
18fd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
18fe0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
18ff0 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
19000 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
19010 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
19020 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
19030 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
19040 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79  sy handler.  Any
19050 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
19060 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
19070 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
19080 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
19090 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
190a0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
190b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
190c0 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
190d0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
190e0 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
190f0 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  dler..*/.SQLITE_
19100 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
19110 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
19120 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
19130 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
19140 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19150 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
19160 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  meout.**.** ^Thi
19170 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
19180 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
19190 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
191a0 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
191b0 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
191c0 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
191d0 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
191e0 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
191f0 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
19200 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
19210 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
19220 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
19230 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
19240 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
19250 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
19260 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
19270 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
19280 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
19290 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
192a0 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
192b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
192c0 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
192d0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
192e0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
192f0 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  CKED]..**.** ^Ca
19300 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
19310 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
19320 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
19330 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
19340 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
19350 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
19360 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
19370 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
19380 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
19390 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
193a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
193b0 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
193c0 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
193d0 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
193e0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
193f0 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
19400 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
19410 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
19420 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
19430 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
19440 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
19450 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
19460 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
19470 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
19480 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
19490 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
194a0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
194b0 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
194c0 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
194d0 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
194e0 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
194f0 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
19500 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
19510 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
19520 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
19530 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
19540 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
19550 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
19560 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
19570 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
19580 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
19590 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
195a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
195b0 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
195c0 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
195d0 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
195e0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
195f0 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
19600 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
19610 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
19620 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
19630 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
19640 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
19650 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
19660 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
19670 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
19680 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
19690 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
196a0 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
196b0 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
196c0 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
196d0 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
196e0 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
196f0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
19700 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
19710 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
19720 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
19730 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
19740 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
19750 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
19760 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
19770 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
19780 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
19790 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
197a0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
197b0 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
197c0 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
197d0 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
197e0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
197f0 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
19800 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
19810 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
19820 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
19830 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
19840 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
19850 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
19860 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
19870 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
19880 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
19890 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
198a0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
198b0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
198c0 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
198d0 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
198e0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
198f0 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
19900 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
19910 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
19920 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
19930 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
19940 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
19950 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
19960 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
19970 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
19980 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
19990 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
199a0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
199b0 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
199c0 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
199d0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
199e0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
199f0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
19a00 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
19a10 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
19a20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
19a30 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
19a40 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
19a50 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
19a60 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
19a70 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
19a80 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
19a90 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
19aa0 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
19ab0 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
19ac0 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
19ad0 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
19ae0 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
19af0 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
19b00 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
19b10 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
19b20 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
19b30 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
19b40 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
19b50 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
19b60 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
19b70 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
19b80 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
19b90 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
19ba0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
19bb0 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
19bc0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
19bd0 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
19be0 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
19bf0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
19c00 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
19c10 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
19c20 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
19c30 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
19c40 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
19c50 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
19c60 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
19c70 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
19c80 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
19c90 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
19ca0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
19cb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19cc0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
19cd0 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
19ce0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
19cf0 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
19d00 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
19d10 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
19d20 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
19d30 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
19d40 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
19d50 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
19d60 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
19d70 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
19d80 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
19d90 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
19da0 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
19db0 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
19dc0 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
19dd0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
19de0 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
19df0 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
19e00 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
19e10 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
19e20 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
19e30 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
19e40 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
19e50 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
19e60 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
19e70 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
19e80 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
19e90 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
19ea0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
19eb0 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
19ec0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
19ed0 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
19ee0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
19ef0 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
19f00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
19f10 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
19f20 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
19f30 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
19f40 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
19f50 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
19f60 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
19f70 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
19f80 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
19f90 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
19fa0 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
19fb0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
19fc0 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
19fd0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
19fe0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
19ff0 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
1a000 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
1a010 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
1a020 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
1a030 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
1a040 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
1a050 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
1a060 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
1a070 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
1a080 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
1a090 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
1a0a0 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
1a0b0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
1a0c0 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
1a0d0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
1a0e0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1a0f0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1a100 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51  errmsg()]..*/.SQ
1a110 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1a120 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
1a130 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1a140 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
1a150 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
1a160 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1a170 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
1a180 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
1a190 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
1a1a0 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
1a1b0 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
1a1c0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
1a1d0 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
1a1e0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1a1f0 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
1a200 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
1a210 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
1a220 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1a230 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
1a240 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
1a250 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
1a260 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
1a270 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
1a280 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1a290 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1a2a0 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
1a2b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1a2c0 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
1a2d0 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
1a2e0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1a2f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1a300 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
1a310 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
1a320 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1a330 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
1a340 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1a350 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ry..**.** ^The s
1a360 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1a370 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
1a380 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
1a390 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
1a3a0 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
1a3b0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
1a3c0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
1a3d0 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
1a3e0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1a3f0 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
1a400 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
1a410 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
1a420 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
1a430 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
1a440 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
1a450 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
1a460 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
1a470 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1a480 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
1a490 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1a4a0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
1a4b0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
1a4c0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1a4d0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
1a4e0 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
1a4f0 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
1a500 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1a510 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
1a520 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
1a530 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
1a540 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
1a550 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1a560 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
1a570 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
1a580 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
1a590 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
1a5a0 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
1a5b0 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
1a5c0 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
1a5d0 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
1a5e0 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
1a5f0 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
1a600 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
1a610 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
1a620 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
1a630 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1a640 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
1a650 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
1a660 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
1a670 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1a680 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
1a690 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
1a6a0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
1a6b0 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
1a6c0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
1a6d0 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
1a6e0 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
1a6f0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1a700 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
1a710 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
1a720 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
1a730 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
1a740 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
1a750 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
1a760 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1a770 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
1a780 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
1a790 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
1a7a0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
1a7b0 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
1a7c0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
1a7d0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1a7e0 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
1a7f0 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
1a800 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
1a810 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
1a820 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1a830 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
1a840 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
1a850 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
1a860 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
1a870 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
1a880 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
1a890 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
1a8a0 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
1a8b0 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
1a8c0 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
1a8d0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
1a8e0 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
1a8f0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1a900 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
1a910 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1a920 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
1a930 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1a940 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
1a950 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
1a960 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
1a970 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
1a980 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
1a990 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
1a9a0 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
1a9b0 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
1a9c0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1a9d0 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
1a9e0 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
1a9f0 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
1aa00 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
1aa10 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1aa20 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1aa30 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1aa40 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1aa50 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1aa60 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1aa70 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1aa80 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1aa90 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1aaa0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1aab0 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1aac0 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1aad0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1aae0 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1aaf0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1ab00 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1ab10 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1ab20 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1ab30 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1ab40 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1ab50 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1ab60 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1ab70 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1ab80 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1ab90 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1aba0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1abb0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1abc0 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1abd0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1abe0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1abf0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1ac00 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1ac10 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1ac20 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1ac30 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1ac40 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1ac50 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1ac60 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1ac70 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1ac80 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1ac90 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1aca0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1acb0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1acc0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1acd0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1ace0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1acf0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1ad00 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1ad10 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1ad20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1ad30 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1ad40 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1ad50 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1ad60 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1ad70 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1ad80 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1ad90 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1ada0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1adb0 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1adc0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1add0 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1ade0 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1adf0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1ae00 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1ae10 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1ae20 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1ae30 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1ae40 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1ae50 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1ae60 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1ae70 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1ae80 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1ae90 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1aea0 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1aeb0 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1aec0 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1aed0 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1aee0 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1aef0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1af00 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1af10 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1af20 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1af30 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1af40 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1af50 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1af60 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1af70 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1af80 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1af90 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1afa0 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1afb0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1afc0 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1afd0 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1afe0 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1aff0 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1b000 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1b010 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1b020 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1b030 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1b040 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1b050 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1b060 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1b070 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1b080 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1b090 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1b0a0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1b0b0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1b0c0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1b0d0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1b0e0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1b0f0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1b100 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1b110 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1b120 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1b130 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1b140 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1b150 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1b160 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1b170 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1b180 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
1b190 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
1b1a0 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
1b1b0 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
1b1c0 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
1b1d0 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
1b1e0 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
1b1f0 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
1b200 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
1b210 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
1b220 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
1b230 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
1b240 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1b250 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1b260 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1b270 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
1b280 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1b290 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1b2a0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49  , va_list);.SQLI
1b2b0 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
1b2c0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
1b2d0 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1b2e0 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54  ar*, ...);.SQLIT
1b2f0 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
1b300 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
1b310 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1b320 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
1b330 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b340 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
1b350 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
1b360 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
1b370 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
1b380 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
1b390 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
1b3a0 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
1b3b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
1b3c0 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
1b3d0 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
1b3e0 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
1b3f0 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
1b400 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
1b410 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
1b420 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
1b430 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
1b440 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
1b450 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
1b460 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
1b470 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1b480 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
1b490 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
1b4a0 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
1b4b0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
1b4c0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1b4d0 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
1b4e0 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
1b4f0 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
1b500 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
1b510 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
1b520 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
1b530 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
1b540 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1b550 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
1b560 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
1b570 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b580 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
1b590 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
1b5a0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
1b5b0 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
1b5c0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  nter..**.** ^Cal
1b5d0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
1b5e0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
1b5f0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
1b600 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1b610 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1b620 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1b630 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
1b640 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
1b650 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
1b660 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
1b670 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
1b680 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
1b690 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
1b6a0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
1b6b0 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
1b6c0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
1b6d0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1b6e0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
1b6f0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
1b700 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
1b710 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
1b720 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
1b730 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
1b740 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
1b750 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
1b760 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
1b770 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
1b780 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1b790 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
1b7a0 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
1b7b0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
1b7c0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1b7d0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
1b7e0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
1b7f0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
1b800 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
1b810 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
1b820 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
1b830 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1b840 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1b850 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1b860 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1b870 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
1b880 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1b890 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1b8a0 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1b8b0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
1b8c0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
1b8d0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
1b8e0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1b8f0 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
1b900 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
1b910 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
1b920 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
1b930 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66  er.)^ ^ If the f
1b940 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1b950 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1b960 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
1b970 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1b980 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1b990 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1b9a0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1b9b0 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
1b9c0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
1b9d0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1b9e0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1b9f0 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
1ba00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1ba10 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
1ba20 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
1ba30 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
1ba40 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
1ba50 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
1ba60 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1ba70 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20  3_free(P) where 
1ba80 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  P is the first p
1ba90 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1baa0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1bab0 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
1bac0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
1bad0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
1bae0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
1baf0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
1bb00 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
1bb10 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
1bb20 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
1bb30 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
1bb40 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
1bb50 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1bb60 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
1bb70 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
1bb80 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1bb90 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
1bba0 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
1bbb0 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
1bbc0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1bbd0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1bbe0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
1bbf0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
1bc00 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
1bc10 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
1bc20 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
1bc30 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1bc40 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
1bc50 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1bc60 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
1bc70 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1bc80 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  c() and sqlite3_
1bc90 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
1bca0 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
1bcb0 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
1bcc0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
1bcd0 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
1bce0 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
1bcf0 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
1bd00 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
1bd10 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
1bd20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
1bd30 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
1bd40 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
1bd50 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
1bd60 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
1bd70 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
1bd80 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
1bd90 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
1bda0 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
1bdb0 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
1bdc0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
1bdd0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
1bde0 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
1bdf0 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
1be00 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
1be10 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
1be20 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1be30 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
1be40 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74  d..**.** Prior t
1be50 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  o SQLite version
1be60 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e   3.7.10, the Win
1be70 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
1be80 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a  e layer called.*
1be90 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
1bea0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1beb0 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
1bec0 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
1bed0 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
1bee0 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
1bef0 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
1bf00 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
1bf10 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
1bf20 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
1bf30 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e  e particular Win
1bf40 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
1bf50 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
1bf60 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
1bf70 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62  were detected, b
1bf80 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20  ut.** they were 
1bf90 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
1bfa0 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
1bfb0 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
1bfc0 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
1bfd0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
1bfe0 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  M]..**.** The po
1bff0 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
1c000 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
1c010 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1c020 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d  _realloc()].** m
1c030 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
1c040 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
1c050 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
1c060 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76  m a prior.** inv
1c070 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
1c080 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
1c090 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1c0a0 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a  c()] that have.*
1c0b0 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72  * not yet been r
1c0c0 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eleased..**.** T
1c0d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
1c0e0 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
1c0f0 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
1c100 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20  f.** a block of 
1c110 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
1c120 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
1c130 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
1c140 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
1c150 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c160 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
1c170 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
1c180 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c  malloc(int);.SQL
1c190 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
1c1a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
1c1b0 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  id*, int);.SQLIT
1c1c0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1c1d0 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
1c1e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c1f0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
1c200 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
1c210 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
1c220 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
1c230 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
1c240 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
1c250 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
1c260 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1c270 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1c280 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1c290 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
1c2a0 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
1c2b0 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
1c2c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1c2d0 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
1c2e0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1c2f0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1c300 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1c310 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1c320 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
1c330 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
1c340 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
1c350 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
1c360 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
1c370 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1c380 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
1c390 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
1c3a0 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
1c3b0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1c3c0 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
1c3d0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1c3e0 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
1c3f0 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
1c400 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1c410 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1c420 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1c430 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1c440 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
1c450 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
1c460 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
1c470 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
1c480 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
1c490 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
1c4a0 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
1c4b0 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
1c4c0 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
1c4d0 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
1c4e0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
1c4f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1c500 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
1c510 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
1c520 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
1c530 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
1c540 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
1c550 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1c560 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
1c570 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
1c580 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
1c590 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1c5a0 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
1c5b0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
1c5c0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
1c5d0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1c5e0 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
1c5f0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1c600 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
1c610 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49  e reset..*/.SQLI
1c620 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
1c630 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1c640 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
1c650 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1c660 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1c670 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1c680 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
1c690 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c6a0 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
1c6b0 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
1c6c0 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  r.**.** SQLite c
1c6d0 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
1c6e0 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
1c6f0 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
1c700 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
1c710 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
1c720 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52  andom [ROWID | R
1c730 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65  OWIDs] when inse
1c740 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
1c750 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
1c760 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
1c770 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
1c780 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d  possible [ROWID]
1c790 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
1c7a0 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
1c7b0 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
1c7c0 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
1c7d0 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
1c7e0 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
1c7f0 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
1c800 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
1c810 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
1c820 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
1c830 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  urposes..**.** ^
1c840 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
1c850 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
1c860 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
1c870 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
1c880 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  P..**.** ^The fi
1c890 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f  rst time this ro
1c8a0 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64  utine is invoked
1c8b0 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61   (either interna
1c8c0 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65  lly or by.** the
1c8d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68   application) th
1c8e0 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64  e PRNG is seeded
1c8f0 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
1c900 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
1c910 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
1c920 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ss method of the
1c930 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1c940 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
1c950 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71  * ^On all subseq
1c960 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73  uent invocations
1c970 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  , the pseudo-ran
1c980 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
1c990 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
1c9a0 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
1c9b0 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
1c9c0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
1c9d0 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
1c9e0 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  od..*/.SQLITE_AP
1c9f0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
1ca00 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c  andomness(int N,
1ca10 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a   void *P);../*.*
1ca20 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
1ca30 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
1ca40 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
1ca50 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1ca60 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
1ca70 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  n authorizer cal
1ca80 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
1ca90 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1caa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1cab0 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
1cac0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1cad0 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
1cae0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1caf0 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
1cb00 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
1cb10 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
1cb20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
1cb30 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
1cb40 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
1cb50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
1cb60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1cb70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
1cb80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1cb90 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v2()].  ^At vari
1cba0 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
1cbb0 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
1cbc0 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
1cbd0 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
1cbe0 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
1cbf0 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
1cc00 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
1cc10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1cc20 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
1cc30 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
1cc40 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
1cc50 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
1cc60 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
1cc70 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
1cc80 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
1cc90 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
1cca0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
1ccb0 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
1ccc0 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
1ccd0 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
1cce0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1ccf0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
1cd00 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
1cd10 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
1cd20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
1cd30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1cd40 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
1cd50 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
1cd60 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
1cd70 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
1cd80 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
1cd90 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
1cda0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
1cdb0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
1cdc0 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
1cdd0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
1cde0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1cdf0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1ce00 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1ce10 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1ce20 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1ce30 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1ce40 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
1ce50 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1ce60 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
1ce70 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
1ce80 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
1ce90 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
1cea0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1ceb0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1cec0 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
1ced0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1cee0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1cef0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1cf00 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
1cf10 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1cf20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1cf30 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
1cf40 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
1cf50 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
1cf60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1cf70 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
1cf80 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1cf90 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
1cfa0 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
1cfb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1cfc0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
1cfd0 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
1cfe0 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
1cff0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
1d000 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1d010 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
1d020 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
1d030 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
1d040 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
1d050 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
1d060 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
1d070 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
1d080 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
1d090 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
1d0a0 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
1d0b0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1d0c0 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
1d0d0 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
1d0e0 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
1d0f0 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
1d100 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
1d110 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
1d120 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
1d130 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
1d140 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1d150 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
1d160 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
1d170 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1d180 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
1d190 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
1d1a0 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
1d1b0 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
1d1c0 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
1d1d0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
1d1e0 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
1d1f0 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
1d200 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
1d210 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
1d220 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
1d230 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
1d240 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
1d250 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
1d260 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
1d270 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
1d280 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74   table..** ^If t
1d290 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1d2a0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  s [SQLITE_DELETE
1d2b0 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  ] and the callba
1d2c0 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ck returns.** [S
1d2d0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1d2e0 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20  en the [DELETE] 
1d2f0 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
1d300 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74  ds but the.** [t
1d310 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
1d320 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65  tion] is disable
1d330 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61  d and all rows a
1d340 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76  re deleted indiv
1d350 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41  idually..**.** A
1d360 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
1d370 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
1d380 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1d390 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
1d3a0 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
1d3b0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  n untrusted sour
1d3c0 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
1d3d0 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
1d3e0 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20  ments.** do not 
1d3f0 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
1d400 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  ta they are not 
1d410 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
1d420 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
1d430 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78  not.** try to ex
1d440 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
1d450 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
1d460 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
1d470 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
1d480 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
1d490 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
1d4a0 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
1d4b0 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
1d4c0 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
1d4d0 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
1d4e0 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
1d4f0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
1d500 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
1d510 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
1d520 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
1d530 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
1d540 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
1d550 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
1d560 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
1d570 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
1d580 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
1d590 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b  d SQL is being [
1d5a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1d5b0 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74  | prepared] that
1d5c0 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  .** disallows ev
1d5d0 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20  erything except 
1d5e0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
1d5f0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  nts..**.** Appli
1d600 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65  cations that nee
1d610 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c  d to process SQL
1d620 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20   from untrusted 
1d630 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74  sources.** might
1d640 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c   also consider l
1d650 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65  owering resource
1d660 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73   limits using [s
1d670 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
1d680 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20  ** and limiting 
1d690 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73  database size us
1d6a0 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67  ing the [max_pag
1d6b0 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
1d6c0 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e  ].** in addition
1d6d0 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74   to using an aut
1d6e0 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  horizer..**.** ^
1d6f0 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61  (Only a single a
1d700 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
1d710 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
1d720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d730 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
1d740 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
1d750 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1d760 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
1d770 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
1d780 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c  call.)^  ^Disabl
1d790 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  e the authorizer
1d7a0 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61   by installing a
1d7b0 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a   NULL callback..
1d7c0 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1d7d0 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  r is disabled by
1d7e0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
1d7f0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1d800 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
1d810 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
1d820 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
1d830 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1d840 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1d850 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72  voked the author
1d860 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  izer callback..*
1d870 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1d880 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d890 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1d8a0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1d8b0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1d8c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d8d0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1d8e0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1d8f0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1d900 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71  .**.** ^When [sq
1d910 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1d920 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
1d930 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
1d940 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
1d950 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
1d960 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  -prepared during
1d970 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1d980 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
1d990 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
1d9a0 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
1d9b0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
1d9c0 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
1d9d0 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
1d9e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
1d9f0 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
1da00 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
1da10 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
1da20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61  ^Note that the a
1da30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1da40 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
1da50 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
1da60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1da70 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1da80 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
1da90 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
1daa0 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
1dab0 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
1dac0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
1dad0 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
1dae0 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
1daf0 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
1db00 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
1db10 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
1db20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1db30 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
1db40 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
1db50 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
1db60 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ge..*/.SQLITE_AP
1db70 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  I int sqlite3_se
1db80 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
1db90 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
1dba0 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
1dbb0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
1dbc0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1dbd0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1dbe0 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
1dbf0 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
1dc00 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1dc10 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
1dc20 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1dc30 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1dc40 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1dc50 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
1dc60 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
1dc70 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
1dc80 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
1dc90 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
1dca0 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
1dcb0 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
1dcc0 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
1dcd0 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
1dce0 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
1dcf0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
1dd00 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1dd10 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
1dd20 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
1dd30 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1dd40 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e  rmation..**.** N
1dd50 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f  ote that SQLITE_
1dd60 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75  IGNORE is also u
1dd70 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45  sed as a [SQLITE
1dd80 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75  _ROLLBACK | retu
1dd90 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d  rn code].** from
1dda0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
1ddb0 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
1ddc0 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
1ddd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1dde0 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
1ddf0 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
1de00 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
1de10 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
1de20 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
1de30 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
1de40 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
1de50 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
1de60 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
1de70 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1de80 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
1de90 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1dea0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1deb0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
1dec0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
1ded0 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
1dee0 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
1def0 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
1df00 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
1df10 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
1df20 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1df30 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
1df40 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1df50 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
1df60 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
1df70 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
1df80 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
1df90 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
1dfa0 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
1dfb0 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
1dfc0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
1dfd0 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
1dfe0 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
1dff0 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
1e000 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
1e010 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
1e020 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
1e030 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
1e040 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
1e050 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
1e060 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
1e070 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
1e080 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
1e090 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
1e0a0 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
1e0b0 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
1e0c0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1e0d0 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
1e0e0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
1e0f0 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
1e100 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1e110 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1e120 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
1e130 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
1e140 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
1e150 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
1e160 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1e170 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e180 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
1e190 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
1e1a0 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
1e1b0 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
1e1c0 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
1e1d0 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
1e1e0 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
1e1f0 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
1e200 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
1e210 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
1e220 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
1e230 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e240 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e250 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
1e260 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
1e270 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
1e280 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1e290 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1e2a0 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
1e2b0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1e2c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1e2d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1e2e0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1e2f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1e300 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1e310 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e320 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1e330 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
1e340 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1e350 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1e360 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e370 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1e380 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
1e390 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1e3a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1e3b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e3c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1e3d0 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
1e3e0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1e3f0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1e400 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e410 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1e420 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
1e430 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1e440 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e450 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e460 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
1e470 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
1e480 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1e490 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e4a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e4b0 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
1e4c0 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
1e4d0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1e4e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e4f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e500 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
1e510 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
1e520 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1e530 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e540 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e550 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
1e560 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
1e570 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1e580 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1e590 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e5a0 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
1e5b0 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
1e5c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1e5d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1e5e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e5f0 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
1e600 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
1e610 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1e620 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1e630 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1e640 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
1e650 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
1e660 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1e670 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1e680 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1e690 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
1e6a0 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
1e6b0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1e6c0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1e6d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1e6e0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1e6f0 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
1e700 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1e710 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1e720 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1e730 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
1e740 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
1e750 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1e760 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1e770 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1e780 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
1e790 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
1e7a0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1e7b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1e7c0 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
1e7d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
1e7e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1e7f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1e800 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e810 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
1e820 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
1e830 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
1e840 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
1e850 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
1e860 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
1e870 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
1e880 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1e890 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1e8a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e8b0 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
1e8c0 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
1e8d0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1e8e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e8f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e900 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
1e910 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
1e920 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1e930 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e940 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e950 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
1e960 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
1e970 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e980 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1e990 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e9a0 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
1e9b0 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
1e9c0 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
1e9d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e9e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e9f0 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
1ea00 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
1ea10 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
1ea20 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1ea30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ea40 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
1ea50 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
1ea60 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
1ea70 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1ea80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ea90 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
1eaa0 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
1eab0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
1eac0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ead0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1eae0 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
1eaf0 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
1eb00 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1eb10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1eb20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1eb30 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
1eb40 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
1eb50 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1eb60 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1eb70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1eb80 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
1eb90 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
1eba0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1ebb0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1ebc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
1ebd0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
1ebe0 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
1ebf0 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
1ec00 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
1ec10 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
1ec20 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
1ec30 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
1ec40 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
1ec50 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
1ec60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
1ec70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ec80 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
1ec90 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
1eca0 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
1ecb0 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
1ecc0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1ecd0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1ece0 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
1ecf0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
1ed00 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
1ed10 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
1ed20 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
1ed30 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
1ed40 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1ed50 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1ed60 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1ed70 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
1ed80 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
1ed90 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
1eda0 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
1edb0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
1edc0 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
1edd0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
1ede0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
1edf0 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
1ee00 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
1ee10 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
1ee20 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
1ee30 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
1ee40 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
1ee50 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
1ee60 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
1ee70 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
1ee80 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
1ee90 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
1eea0 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
1eeb0 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
1eec0 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
1eed0 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
1eee0 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
1eef0 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
1ef00 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
1ef10 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
1ef20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
1ef30 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
1ef40 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
1ef50 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  e option can be 
1ef60 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a  used to limit.**
1ef70 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b   the length of [
1ef80 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d  bound parameter]
1ef90 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68   expansion in th
1efa0 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69  e output of sqli
1efb0 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a  te3_trace()..**.
1efc0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1efd0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1efe0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1eff0 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
1f000 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
1f010 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
1f020 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
1f030 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
1f040 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
1f050 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1f060 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
1f070 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
1f080 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
1f090 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
1f0a0 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
1f0b0 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
1f0c0 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
1f0d0 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
1f0e0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
1f0f0 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
1f100 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
1f110 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
1f120 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
1f130 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
1f140 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
1f150 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
1f160 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
1f170 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
1f180 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
1f190 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
1f1a0 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
1f1b0 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
1f1c0 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
1f1d0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
1f1e0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
1f1f0 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
1f200 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
1f210 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
1f220 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
1f230 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
1f240 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1f250 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ite..*/.SQLITE_A
1f260 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
1f270 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
1f280 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
1f290 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1f2a0 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
1f2b0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50  E_API SQLITE_EXP
1f2c0 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
1f2d0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1f2e0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
1f2f0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
1f300 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
1f310 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
1f320 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1f330 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
1f340 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
1f350 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1f360 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1f370 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
1f380 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
1f390 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
1f3a0 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
1f3b0 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
1f3c0 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
1f3d0 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
1f3e0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
1f3f0 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
1f400 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
1f410 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1f420 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
1f430 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
1f440 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
1f450 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
1f460 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
1f470 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
1f480 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
1f490 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
1f4a0 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
1f4b0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
1f4c0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
1f4d0 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
1f4e0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1f4f0 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
1f500 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70  eter N is the ap
1f510 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72  proximate number
1f520 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
1f530 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
1f540 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
1f550 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
1f560 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
1f570 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
1f580 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20  he callback X.  
1f590 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68  ^If N is less th
1f5a0 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20  an one then the 
1f5b0 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64  progress.** hand
1f5c0 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ler is disabled.
1f5d0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
1f5e0 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
1f5f0 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
1f600 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
1f610 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
1f620 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
1f630 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
1f640 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
1f650 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
1f660 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
1f670 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
1f680 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
1f690 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1f6a0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
1f6b0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
1f6c0 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
1f6d0 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
1f6e0 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
1f6f0 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
1f700 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
1f710 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1f720 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
1f730 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
1f740 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
1f750 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
1f760 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1f770 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
1f780 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
1f790 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
1f7a0 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
1f7b0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
1f7c0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1f7d0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1f7e0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1f7f0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1f800 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1f810 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
1f820 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
1f830 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1f840 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1f850 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1f860 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1f870 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1f880 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1f890 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1f8a0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1f8b0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1f8c0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1f8d0 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
1f8e0 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
1f8f0 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
1f900 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
1f910 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f920 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
1f930 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1f940 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
1f950 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
1f960 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
1f970 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
1f980 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
1f990 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1f9a0 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
1f9b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
1f9c0 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
1f9d0 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
1f9e0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1f9f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
1fa00 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
1fa10 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
1fa20 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
1fa30 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
1fa40 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
1fa50 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
1fa60 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
1fa70 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
1fa80 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
1fa90 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
1faa0 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
1fab0 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
1fac0 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
1fad0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
1fae0 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
1faf0 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
1fb00 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
1fb10 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
1fb20 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
1fb30 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
1fb40 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
1fb50 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
1fb60 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1fb70 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
1fb80 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
1fb90 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
1fba0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
1fbb0 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
1fbc0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
1fbd0 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
1fbe0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1fbf0 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
1fc00 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
1fc10 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
1fc20 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
1fc30 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
1fc40 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
1fc50 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
1fc60 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
1fc70 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
1fc80 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1fc90 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
1fca0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
1fcb0 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
1fcc0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1fcd0 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69  UTF-8 if.** sqli
1fce0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
1fcf0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1fd00 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a  is called and.**
1fd10 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1fd20 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1fd30 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   if sqlite3_open
1fd40 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a  16() is used..**
1fd50 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
1fd60 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
1fd70 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
1fd80 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
1fd90 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
1fda0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
1fdb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1fdc0 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
1fdd0 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
1fde0 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
1fdf0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
1fe00 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
1fe10 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
1fe20 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
1fe30 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
1fe40 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
1fe50 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
1fe60 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
1fe70 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
1fe80 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
1fe90 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
1fea0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
1feb0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
1fec0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
1fed0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
1fee0 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
1fef0 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
1ff00 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
1ff10 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
1ff20 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
1ff30 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
1ff40 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
1ff50 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1ff60 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
1ff70 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
1ff80 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1ff90 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
1ffa0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1ffb0 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
1ffc0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
1ffd0 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
1ffe0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
1fff0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
20000 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
20010 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
20020 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
20030 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
20040 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
20050 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
20060 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
20070 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
20080 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
20090 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
200a0 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
200b0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
200c0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
200d0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
200e0 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
200f0 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
20100 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
20110 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
20120 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
20130 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
20140 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
20150 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
20160 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
20170 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
20180 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
20190 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
201a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
201b0 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
201c0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
201d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
201e0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
201f0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
20200 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
20210 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
20220 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
20230 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
20240 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
20250 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
20260 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
20270 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
20280 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
20290 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
202a0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
202b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
202c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
202d0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
202e0 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
202f0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
20300 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
20310 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
20320 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
20330 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
20340 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
20350 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
20360 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
20370 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
20380 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
20390 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
203a0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
203b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
203c0 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
203d0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
203e0 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
203f0 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
20400 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
20410 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
20420 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
20430 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
20440 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
20450 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
20460 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] 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 20 6f 70 65 6e   connection open
20490 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
204a0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
204b0 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
204c0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
204d0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
204e0 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
204f0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
20500 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
20510 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
20520 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
20530 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
20540 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
20550 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
20560 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
20570 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
20580 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
20590 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
205a0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
205b0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
205c0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
205d0 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
205e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
205f0 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
20600 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
20610 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20620 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
20630 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
20640 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
20650 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
20660 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
20670 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
20680 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
20690 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
206a0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
206b0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
206c0 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
206d0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
206e0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
206f0 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
20700 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20710 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
20720 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
20730 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
20740 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
20750 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
20760 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
20770 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
20780 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
20790 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
207a0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
207b0 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
207c0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
207d0 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
207e0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
207f0 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
20800 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
20810 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
20820 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
20830 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
20840 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
20850 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
20860 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
20870 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
20880 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
20890 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
208a0 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
208b0 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
208c0 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
208d0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
208e0 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
208f0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
20900 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
20910 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
20920 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
20930 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
20940 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
20950 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
20960 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
20970 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
20980 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
20990 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
209a0 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
209b0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
209c0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
209d0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
209e0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
209f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
20a00 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
20a10 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
20a20 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
20a30 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
20a40 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
20a50 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
20a60 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
20a70 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
20a80 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
20a90 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
20aa0 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
20ab0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
20ac0 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
20ad0 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
20ae0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
20af0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
20b00 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
20b10 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
20b20 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
20b30 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
20b40 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
20b50 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
20b60 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
20b70 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
20b80 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
20b90 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
20ba0 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
20bb0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
20bc0 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
20bd0 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
20be0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
20bf0 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
20c00 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
20c10 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
20c20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
20c30 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
20c40 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
20c50 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
20c60 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
20c70 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
20c80 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
20c90 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
20ca0 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
20cb0 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
20cc0 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
20cd0 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
20ce0 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
20cf0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
20d00 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
20d10 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
20d20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
20d30 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
20d40 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
20d50 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
20d60 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
20d70 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
20d80 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
20d90 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
20da0 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
20db0 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
20dc0 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
20dd0 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
20de0 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
20df0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
20e00 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
20e10 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
20e20 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
20e30 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
20e40 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
20e50 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
20e60 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
20e70 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
20e80 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
20e90 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
20ea0 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
20eb0 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
20ec0 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
20ed0 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
20ee0 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
20ef0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
20f00 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
20f10 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
20f20 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
20f30 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
20f40 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
20f50 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
20f60 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
20f70 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
20f80 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
20f90 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
20fa0 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
20fb0 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73   .** ^On windows
20fc0 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
20fd0 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
20fe0 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
20ff0 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
21000 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
21010 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  ")..**.** [[core
21020 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
21030 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
21040 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
21050 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
21060 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
21070 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
21080 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
21090 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
210a0 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
210b0 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
210c0 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
210d0 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
210e0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
210f0 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  ree query parame
21100 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
21110 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
21120 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
21130 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
21140 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
21150 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
21160 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
21170 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
21180 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
21190 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
211a0 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
211b0 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
211c0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
211d0 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
211e0 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
211f0 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
21200 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
21210 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
21220 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
21230 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
21240 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
21250 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
21260 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
21270 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
21280 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
21290 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
212a0 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
212b0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
212c0 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
212d0 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
212e0 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
212f0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
21300 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
21310 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
21320 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
21330 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
21340 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
21350 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
21360 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
21370 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
21380 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
21390 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
213a0 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
213b0 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
213c0 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
213d0 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
213e0 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
213f0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
21400 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
21410 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
21420 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
21430 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
21440 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
21450 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
21460 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
21470 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
21480 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21490 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
214a0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
214b0 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
214c0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
214d0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
214e0 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
214f0 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
21500 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
21510 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
21520 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
21530 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
21540 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
21550 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
21560 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
21570 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
21580 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
21590 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
215a0 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
215b0 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
215c0 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
215d0 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
215e0 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
215f0 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
21600 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
21610 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
21620 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
21630 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
21640 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
21650 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
21660 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
21670 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
21680 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
21690 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
216a0 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
216b0 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
216c0 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
216d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
216e0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
216f0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
21700 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
21710 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
21720 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
21730 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
21740 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
21750 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
21760 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
21770 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
21780 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
21790 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
217a0 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
217b0 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
217c0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
217d0 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
217e0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
217f0 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
21800 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
21810 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
21820 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
21830 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
21840 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
21850 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
21860 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
21870 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
21880 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
21890 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
218a0 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
218b0 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
218c0 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
218d0 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71  any behavior req
218e0 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e  uested by settin
218f0 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  g.**     SQLITE_
21900 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
21910 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e  E or SQLITE_OPEN
21920 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61  _SHAREDCACHE fla
21930 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  g..** </ul>.**.*
21940 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
21950 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
21960 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
21970 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
21980 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
21990 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
219a0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
219b0 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
219c0 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
219d0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
219e0 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
219f0 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
21a00 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
21a10 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
21a20 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
21a30 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
21a40 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
21a50 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
21a60 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
21a70 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
21a80 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
21a90 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
21aa0 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
21ab0 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
21ac0 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
21ad0 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
21ae0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
21af0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
21b00 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
21b10 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
21b20 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
21b30 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
21b40 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
21b50 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
21b60 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
21b70 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
21b80 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
21b90 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
21ba0 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
21bb0 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
21bc0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
21bd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
21be0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
21bf0 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
21c00 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
21c10 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
21c20 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
21c30 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
21c40 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
21c50 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
21c60 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
21c70 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
21c80 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
21c90 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
21ca0 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
21cb0 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
21cc0 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
21cd0 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
21ce0 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
21cf0 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
21d00 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
21d10 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
21d20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
21d30 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
21d40 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
21d50 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
21d60 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
21d70 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
21d80 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
21d90 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
21da0 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
21db0 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
21dc0 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
21dd0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
21de0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
21df0 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
21e00 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
21e10 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
21e20 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
21e30 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
21e40 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
21e50 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
21e60 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
21e70 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
21e80 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
21e90 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
21ea0 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
21eb0 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
21ec0 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
21ed0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
21ee0 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
21ef0 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64  =unix-nolock <td
21f00 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70  >.**          Op
21f10 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  en file "/home/f
21f20 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73  red/data.db". Us
21f30 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  e the special VF
21f40 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e  S "unix-nolock".
21f50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
21f60 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
21f70 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
21f80 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
21f90 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
21fa0 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
21fb0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
21fc0 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
21fd0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
21fe0 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
21ff0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
22000 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
22010 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
22020 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
22030 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
22040 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
22050 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
22060 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
22070 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
22080 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
22090 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
220a0 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
220b0 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
220c0 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
220d0 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
220e0 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
220f0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
22100 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
22110 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
22120 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
22130 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
22140 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
22150 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
22160 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
22170 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
22180 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
22190 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
221a0 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
221b0 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
221c0 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
221d0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
221e0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
221f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
22200 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
22210 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
22220 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
22230 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
22240 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
22250 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
22260 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
22270 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
22280 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
22290 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
222a0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
222b0 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
222c0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
222d0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
222e0 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
222f0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
22300 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
22310 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
22320 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
22330 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
22340 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
22350 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
22360 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
22370 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
22380 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
22390 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
223a0 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
223b0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
223c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
223d0 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
223e0 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
223f0 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
22400 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
22410 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
22420 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
22430 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
22440 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51  directory].*/.SQ
22450 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
22460 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
22470 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
22480 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
22490 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
224a0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
224b0 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
224c0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
224d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51   handle */.);.SQ
224e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
224f0 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
22500 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
22510 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
22520 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
22530 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
22540 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
22550 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
22560 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
22570 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
22580 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22590 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
225a0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
225b0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
225c0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
225d0 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
225e0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
225f0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
22600 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
22610 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
22620 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
22630 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
22640 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
22650 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
22660 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
22670 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
22680 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
22690 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
226a0 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
226b0 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
226c0 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
226d0 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
226e0 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
226f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
22700 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
22710 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
22720 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
22730 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
22740 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
22750 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
22760 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
22770 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
22780 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
22790 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
227a0 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
227b0 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
227c0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
227d0 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
227e0 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
227f0 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
22800 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
22810 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
22820 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
22830 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
22840 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
22850 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
22860 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
22870 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
22880 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
22890 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
228a0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
228b0 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
228c0 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
228d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
228e0 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
228f0 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
22900 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
22910 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
22920 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
22930 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
22940 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
22950 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
22960 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
22970 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
22980 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
22990 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
229a0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
229b0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
229c0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
229d0 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
229e0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
229f0 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
22a00 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
22a10 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
22a20 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
22a30 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
22a40 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
22a50 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
22a60 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
22a70 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
22a80 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
22a90 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
22aa0 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
22ab0 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
22ac0 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
22ad0 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
22ae0 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
22af0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
22b00 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
22b10 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
22b20 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
22b30 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
22b40 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
22b50 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
22b60 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
22b70 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
22b80 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
22b90 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
22ba0 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
22bb0 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
22bc0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
22bd0 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
22be0 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
22bf0 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
22c00 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
22c10 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
22c20 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
22c30 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
22c40 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
22c50 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
22c60 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
22c70 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
22c80 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
22c90 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
22ca0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
22cb0 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
22cc0 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
22cd0 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
22ce0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
22cf0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
22d00 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
22d10 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
22d20 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
22d30 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
22d40 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
22d50 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
22d60 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
22d70 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
22d80 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
22d90 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
22da0 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
22db0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
22dc0 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
22dd0 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
22de0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
22df0 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
22e00 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
22e10 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
22e20 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
22e30 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
22e40 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
22e50 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
22e60 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c  esirable..*/.SQL
22e70 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
22e80 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f  ar *sqlite3_uri_
22e90 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20  parameter(const 
22ea0 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c  char *zFilename,
22eb0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
22ec0 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ram);.SQLITE_API
22ed0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69   int sqlite3_uri
22ee0 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63  _boolean(const c
22ef0 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73  har *zFile, cons
22f00 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20  t char *zParam, 
22f10 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 53  int bDefault);.S
22f20 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
22f30 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
22f40 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
22f50 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
22f60 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
22f70 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
22f80 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
22f90 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
22fa0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
22fb0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
22fc0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
22fd0 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
22fe0 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
22ff0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
23000 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
23010 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
23020 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
23030 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
23040 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
23050 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
23060 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
23070 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
23080 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
23090 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
230a0 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
230b0 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
230c0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
230d0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
230e0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
230f0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
23100 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
23110 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
23120 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
23130 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
23140 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
23150 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
23160 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
23170 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
23180 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
23190 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
231a0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
231b0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
231c0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
231d0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
231e0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
231f0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
23200 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
23210 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
23220 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
23230 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
23240 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
23250 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
23260 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
23270 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
23280 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
23290 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
232a0 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
232b0 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
232c0 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
232d0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
232e0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
232f0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
23300 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
23310 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
23320 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
23330 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
23340 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
23350 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
23360 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
23370 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
23380 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
23390 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
233a0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
233b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
233c0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
233d0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
233e0 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
233f0 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
23400 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
23410 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
23420 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
23430 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
23440 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
23450 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
23460 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
23470 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
23480 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
23490 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
234a0 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
234b0 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
234c0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
234d0 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
234e0 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
234f0 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
23500 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
23510 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
23520 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
23530 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
23540 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
23550 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
23560 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
23570 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
23580 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
23590 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
235a0 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
235b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
235c0 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
235d0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
235e0 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
235f0 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
23600 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
23610 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
23620 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
23630 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
23640 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
23650 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
23660 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
23670 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
23680 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
23690 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
236a0 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
236b0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
236c0 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
236d0 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
236e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
236f0 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
23700 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
23710 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
23720 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
23730 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
23740 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72   int sqlite3_err
23750 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
23760 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
23770 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
23780 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
23790 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f  e3 *db);.SQLITE_
237a0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
237b0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
237c0 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45  qlite3*);.SQLITE
237d0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
237e0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
237f0 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  6(sqlite3*);.SQL
23800 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
23810 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73  ar *sqlite3_errs
23820 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  tr(int);../*.** 
23830 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
23840 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
23850 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
23860 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
23870 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
23880 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
23890 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
238a0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
238b0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
238c0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
238d0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
238e0 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
238f0 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
23900 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
23910 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
23920 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
23930 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
23940 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
23950 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
23960 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
23970 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
23980 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
23990 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
239a0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
239b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
239c0 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
239d0 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
239e0 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
239f0 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
23a00 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
23a10 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
23a20 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
23a30 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
23a40 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
23a50 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
23a60 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
23a70 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
23a80 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
23a90 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
23aa0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
23ab0 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
23ac0 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
23ad0 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
23ae0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
23af0 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
23b00 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
23b10 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
23b20 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
23b30 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
23b40 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
23b50 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
23b60 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
23b70 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
23b80 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
23b90 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
23ba0 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
23bb0 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
23bc0 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
23bd0 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  imits.**.** ^(Th
23be0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
23bf0 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
23c00 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
23c10 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
23c20 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
23c30 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
23c40 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
23c50 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
23c60 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
23c70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
23c80 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
23c90 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
23ca0 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
23cb0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
23cc0 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
23cd0 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
23ce0 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
23cf0 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
23d00 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
23d10 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
23d20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
23d30 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
23d40 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
23d50 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
23d60 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
23d70 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
23d80 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
23d90 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
23da0 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
23db0 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
23dc0 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
23dd0 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
23de0 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
23df0 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
23e00 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
23e10 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
23e20 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
23e30 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
23e40 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
23e50 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
23e60 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
23e70 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
23e80 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
23e90 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
23ea0 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
23eb0 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
23ec0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
23ed0 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
23ee0 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
23ef0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
23f00 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
23f10 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
23f20 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
23f30 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
23f40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
23f50 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
23f60 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
23f70 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
23f80 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
23f90 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
23fa0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
23fb0 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
23fc0 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
23fd0 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
23fe0 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
23ff0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
24000 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
24010 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
24020 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
24030 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
24040 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
24050 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
24060 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
24070 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
24080 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
24090 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
240a0 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
240b0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
240c0 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
240d0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
240e0 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
240f0 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
24100 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
24110 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
24120 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
24130 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
24140 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
24150 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
24160 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
24170 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
24180 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
24190 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
241a0 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
241b0 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
241c0 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
241d0 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
241e0 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
241f0 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
24200 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
24210 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
24220 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
24230 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
24240 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
24250 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
24260 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
24270 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
24280 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
24290 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
242a0 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
242b0 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
242c0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
242d0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
242e0 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
242f0 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
24300 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
24310 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
24320 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
24330 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
24340 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
24350 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
24360 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
24370 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
24380 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
24390 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
243a0 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
243b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
243c0 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
243d0 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
243e0 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
243f0 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
24400 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
24410 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
24420 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
24430 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
24440 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
24450 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
24460 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
24470 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
24480 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
24490 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
244a0 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
244b0 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
244c0 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
244d0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
244e0 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
244f0 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
24500 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
24510 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
24520 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
24530 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
24540 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
24550 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
24560 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
24570 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
24580 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e  or table row, in
24590 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a   bytes.<dd>)^.**
245a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
245b0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20  IT_SQL_LENGTH]] 
245c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
245d0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64  IT_SQL_LENGTH</d
245e0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
245f0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
24600 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
24610 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e  , in bytes.</dd>
24620 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
24630 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d  E_LIMIT_COLUMN]]
24640 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
24650 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
24660 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
24670 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
24680 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
24690 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
246a0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
246b0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
246c0 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
246d0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
246e0 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
246f0 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
24700 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
24710 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  lause.</dd>)^.**
24720 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
24730 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20  IT_EXPR_DEPTH]] 
24740 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
24750 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
24760 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
24770 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
24780 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
24790 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
247a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
247b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
247c0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e  POUND_SELECT]] ^
247d0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
247e0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
247f0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
24800 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
24810 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
24820 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
24830 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
24840 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
24850 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20  LIMIT_VDBE_OP]] 
24860 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
24870 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a  IT_VDBE_OP</dt>.
24880 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
24890 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73  um number of ins
248a0 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76  tructions in a v
248b0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70  irtual machine p
248c0 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74  rogram.** used t
248d0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53  o implement an S
248e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  QL statement.  T
248f0 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74  his limit is not
24900 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e   currently.** en
24910 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74  forced, though t
24920 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64  hat might be add
24930 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  ed in some futur
24940 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
24950 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  SQLite.</dd>)^.*
24960 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
24970 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
24980 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
24990 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
249a0 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
249b0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
249c0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
249d0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
249e0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
249f0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
24a00 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ED]] ^(<dt>SQLIT
24a10 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
24a20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
24a30 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
24a40 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
24a50 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
24a60 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  .)^</dd>.**.** [
24a70 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  [SQLITE_LIMIT_LI
24a80 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
24a90 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  H]].** ^(<dt>SQL
24aa0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
24ab0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
24ac0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
24ad0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
24ae0 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
24af0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
24b00 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
24b10 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29  operators.</dd>)
24b20 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
24b30 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
24b40 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64  NUMBER]].** ^(<d
24b50 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
24b60 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f  ARIABLE_NUMBER</
24b70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
24b80 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d  aximum index num
24b90 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61  ber of any [para
24ba0 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c  meter] in an SQL
24bb0 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a   statement.)^.**
24bc0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
24bd0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
24be0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
24bf0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
24c00 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
24c10 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
24c20 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66  h of recursion f
24c30 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64  or triggers.</dd
24c40 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
24c50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
24c60 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
24c70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
24c80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24c90 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
24ca0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24cb0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
24cc0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
24cd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24ce0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
24cf0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
24d00 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
24d10 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
24d20 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
24d30 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
24d40 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
24d50 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
24d60 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
24d70 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
24d80 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
24d90 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
24da0 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
24db0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
24dc0 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
24dd0 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
24de0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
24df0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
24e00 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
24e10 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
24e20 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
24e30 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
24e40 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
24e50 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
24e60 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a          10../*.*
24e70 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
24e80 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
24e90 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52  tement.** KEYWOR
24ea0 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
24eb0 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a  nt compiler}.**.
24ec0 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
24ed0 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
24ee0 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
24ef0 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
24f00 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
24f10 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
24f20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
24f30 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
24f40 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
24f50 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
24f60 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
24f70 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
24f80 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
24f90 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
24fa0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
24fb0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a  _open_v2()] or.*
24fc0 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
24fd0 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62  6()].  The datab
24fe0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
24ff0 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
25000 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  n closed..**.** 
25010 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
25020 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20  ent, "zSql", is 
25030 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
25040 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
25050 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
25060 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
25070 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
25080 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
25090 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
250a0 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  2().** interface
250b0 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
250c0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
250d0 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  16() and sqlite3
250e0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a  _prepare16_v2().
250f0 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  ** use UTF-16..*
25100 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79  *.** ^If the nBy
25110 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
25120 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  ess than zero, t
25130 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
25140 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
25150 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
25160 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
25170 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
25180 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d  then it is the m
25190 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72  aximum.** number
251a0 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20   of  bytes read 
251b0 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65  from zSql.  ^Whe
251c0 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  n nByte is non-n
251d0 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20  egative, the.** 
251e0 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73  zSql string ends
251f0 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66   at either the f
25200 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27  irst '\000' or '
25210 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65  \u0000' characte
25220 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74  r or.** the nByt
25230 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
25240 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
25250 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  . If the caller 
25260 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68  knows.** that th
25270 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
25280 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
25290 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20  ted, then there 
252a0 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65  is a small.** pe
252b0 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
252c0 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64  age to be gained
252d0 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   by passing an n
252e0 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
252f0 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20  hat.** is equal 
25300 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  to the number of
25310 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
25320 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
25330 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
25340 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
25350 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73 20  r bytes as this 
25360 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72 6f  saves SQLite fro
25370 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d  m having to.** m
25380 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
25390 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a  e input string..
253a0 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
253b0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
253c0 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
253d0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
253e0 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
253f0 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
25400 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
25410 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
25420 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
25430 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
25440 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
25450 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
25460 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
25470 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
25480 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
25490 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
254a0 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
254b0 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
254c0 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
254d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
254e0 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
254f0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
25500 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
25510 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
25520 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
25530 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
25540 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
25550 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
25560 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
25570 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
25580 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
25590 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
255a0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
255b0 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
255c0 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
255d0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
255e0 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
255f0 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
25600 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
25610 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
25620 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
25630 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
25640 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
25650 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
25660 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
25670 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
25680 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
25690 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
256a0 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
256b0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
256c0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
256d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
256e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
256f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
25700 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
25710 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
25720 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
25730 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
25740 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
25750 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
25760 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
25770 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
25780 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
25790 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
257a0 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
257b0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
257c0 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
257d0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
257e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
257f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
25800 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
25810 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
25820 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
25830 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
25840 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
25850 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
25860 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
25870 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
25880 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
25890 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
258a0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
258b0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
258c0 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
258d0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
258e0 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
258f0 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
25900 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
25910 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
25920 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
25930 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
25940 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
25950 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20  un it again. As 
25960 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f  many as [SQLITE_
25970 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59  MAX_SCHEMA_RETRY
25980 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c  ].** retries wil
25990 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73  l occur before s
259a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69  qlite3_step() gi
259b0 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72  ves up and retur
259c0 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20  ns an error..** 
259d0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
259e0 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
259f0 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
25a00 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
25a10 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
25a20 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
25a30 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
25a40 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
25a50 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
25a60 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
25a70 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
25a80 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
25a90 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
25aa0 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
25ab0 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
25ac0 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
25ad0 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
25ae0 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
25af0 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
25b00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
25b10 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
25b20 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
25b30 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
25b40 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
25b50 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
25b60 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
25b70 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
25b80 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
25b90 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
25ba0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
25bb0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
25bc0 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
25bd0 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f  c value bound to
25be0 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
25bf0 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
25c00 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63   the .** WHERE c
25c10 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c  lause might infl
25c20 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65  uence the choice
25c30 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66   of query plan f
25c40 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a  or a statement,.
25c50 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74  ** then the stat
25c60 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75  ement will be au
25c70 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
25c80 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68  mpiled, as if th
25c90 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a  ere had been .**
25ca0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
25cb0 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20  , on the first  
25cc0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
25cd0 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
25ce0 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f  any change.** to
25cf0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
25d00 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e  nd_text | bindin
25d10 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72  gs] of that [par
25d20 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68  ameter]. .** ^Th
25d30 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
25d40 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65   of WHERE-clause
25d50 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67   [parameter] mig
25d60 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
25d70 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71   .** choice of q
25d80 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65  uery plan if the
25d90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
25da0 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
25db0 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20   of a [LIKE].** 
25dc0 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  or [GLOB] operat
25dd0 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72  or or if the par
25de0 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72  ameter is compar
25df0 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64  ed to an indexed
25e00 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74   column.** and t
25e10 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
25e20 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65  E_STAT3] compile
25e30 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
25e40 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20  enabled..** the 
25e50 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
25e60 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l>.*/.SQLITE_API
25e70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
25e80 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
25e90 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
25ea0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
25eb0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
25ec0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
25ed0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
25ee0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
25ef0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
25f00 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
25f10 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
25f20 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
25f30 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
25f40 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
25f50 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
25f60 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
25f70 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
25f80 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
25f90 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
25fa0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
25fb0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
25fc0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
25fd0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
25fe0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
25ff0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
26000 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
26010 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
26020 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
26030 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
26040 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
26050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
26060 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
26070 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
26080 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
26090 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
260a0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
260b0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
260c0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
260d0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
260e0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
260f0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
26100 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
26110 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
26120 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
26130 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
26140 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
26150 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
26160 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
26170 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
26180 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
26190 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
261a0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
261b0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
261c0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
261d0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
261e0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
261f0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
26200 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
26210 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
26220 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
26230 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
26240 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
26250 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
26260 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
26270 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
26280 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
26290 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
262a0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
262b0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
262c0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
262d0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
262e0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
262f0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
26300 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
26310 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
26320 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
26330 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
26340 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
26350 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
26360 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
26370 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
26380 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
26390 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
263a0 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
263b0 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
263c0 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
263d0 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  SQL.**.** ^This 
263e0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
263f0 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
26400 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
26410 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
26420 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
26430 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
26440 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26450 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
26460 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
26470 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
26480 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26490 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
264a0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
264b0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
264c0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
264d0 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
264e0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
264f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26500 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
26510 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57   SQL Statement W
26520 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61  rites The Databa
26530 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  se.**.** ^The sq
26540 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
26550 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65  nly(X) interface
26560 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
26570 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61  on-zero) if.** a
26580 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b  nd only if the [
26590 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
265a0 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64  nt] X makes no d
265b0 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f  irect changes to
265c0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
265d0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
265e0 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  file..**.** Note
265f0 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69   that [applicati
26600 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
26610 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20  unctions] or.** 
26620 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
26630 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68   might change th
26640 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72  e database indir
26650 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20  ectly as a side 
26660 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46  effect.  .** ^(F
26670 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
26680 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
26690 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e  fines a function
266a0 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a   "eval()" that .
266b0 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65  ** calls [sqlite
266c0 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20  3_exec()], then 
266d0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
266e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c  L statement woul
266f0 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  d.** change the 
26700 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
26710 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63  rough side-effec
26720 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ts:.**.** <block
26730 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
26740 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44    SELECT eval('D
26750 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20  ELETE FROM t1') 
26760 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72  FROM t2;.** </pr
26770 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
26780 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73  **.** But becaus
26790 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  e the [SELECT] s
267a0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
267b0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
267c0 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69  abase file.** di
267d0 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f  rectly, sqlite3_
267e0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
267f0 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75  would still retu
26800 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a  rn true.)^.**.**
26810 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f   ^Transaction co
26820 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73  ntrol statements
26830 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d   such as [BEGIN]
26840 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c  , [COMMIT], [ROL
26850 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45  LBACK],.** [SAVE
26860 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c  POINT], and [REL
26870 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69  EASE] cause sqli
26880 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
26890 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
268a0 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ue,.** since the
268b0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d   statements them
268c0 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63  selves do not ac
268d0 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68  tually modify th
268e0 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a  e database but.*
268f0 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f  * rather they co
26900 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67  ntrol the timing
26910 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73   of when other s
26920 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79  tatements modify
26930 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73   the .** databas
26940 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48  e.  ^The [ATTACH
26950 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73  ] and [DETACH] s
26960 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63  tatements also c
26970 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ause.** sqlite3_
26980 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
26990 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  to return true s
269a0 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73  ince, while thos
269b0 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  e statements.** 
269c0 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69  change the confi
269d0 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61  guration of a da
269e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
269f0 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d  n, they do not m
26a00 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20  ake .** changes 
26a10 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  to the content o
26a20 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
26a30 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f  iles on disk..*/
26a40 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
26a50 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
26a60 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
26a70 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
26a80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
26a90 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
26aa0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
26ab0 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
26ac0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
26ad0 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e  _stmt_busy(S) in
26ae0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
26af0 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
26b00 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  if the.** [prepa
26b10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
26b20 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65   has been steppe
26b30 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20  d at least once 
26b40 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
26b50 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20  e3_step(S)] but 
26b60 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63  has not run to c
26b70 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72  ompletion and/or
26b80 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65   has not .** bee
26b90 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73  n reset using [s
26ba0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
26bb0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
26bc0 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20  stmt_busy(S).** 
26bd0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
26be0 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20  s false if S is 
26bf0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
26c00 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a   If S is not a .
26c10 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
26c20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  and is not a poi
26c30 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20  nter to a valid 
26c40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26c50 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20  ent].** object, 
26c60 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
26c70 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  r is undefined a
26c80 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
26c90 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  sirable..**.** T
26ca0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
26cb0 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d  n be used in com
26cc0 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65  bination [sqlite
26cd0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a  3_next_stmt()].*
26ce0 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20  * to locate all 
26cf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26d00 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
26d10 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a  ith a database .
26d20 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
26d30 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f  at are in need o
26d40 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20  f being reset.  
26d50 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64  This can be used
26d60 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65  ,.** for example
26d70 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20  , in diagnostic 
26d80 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72  routines to sear
26d90 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20  ch for prepared 
26da0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74  .** statements t
26db0 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20  hat are holding 
26dc0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70  a transaction op
26dd0 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  en..*/.SQLITE_AP
26de0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  I int sqlite3_st
26df0 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f  mt_busy(sqlite3_
26e00 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
26e10 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
26e20 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
26e30 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
26e40 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
26e50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
26e60 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
26e70 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
26e80 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
26e90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26ea0 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
26eb0 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
26ec0 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
26ed0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
26ee0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
26ef0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
26f00 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
26f10 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
26f20 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
26f30 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
26f40 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
26f50 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
26f60 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
26f70 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
26f80 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
26f90 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
26fa0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
26fb0 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
26fc0 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
26fd0 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
26fe0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
26ff0 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
27000 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
27010 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
27020 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
27030 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
27040 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
27050 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27060 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
27070 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
27080 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
27090 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
270a0 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
270b0 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
270c0 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
270d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
270e0 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
270f0 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
27100 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
27110 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
27120 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
27130 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
27140 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
27150 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
27160 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
27170 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
27180 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
27190 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
271a0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
271b0 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
271c0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
271d0 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
271e0 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
271f0 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
27200 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
27210 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
27220 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
27230 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
27240 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
27250 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
27260 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
27270 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
27280 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
27290 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
272a0 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
272b0 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
272c0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
272d0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
272e0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
272f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27300 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
27310 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
27320 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
27330 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
27340 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
27350 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
27360 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
27370 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
27380 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
27390 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
273a0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
273b0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
273c0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
273d0 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
273e0 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
273f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
27400 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27410 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
27420 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
27430 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
27440 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
27450 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
27460 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
27470 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
27480 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
27490 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
274a0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
274b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
274c0 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
274d0 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
274e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
274f0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
27500 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
27510 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
27520 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
27530 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
27540 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
27550 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
27560 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
27570 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
27580 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
27590 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
275a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
275b0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
275c0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
275d0 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
275e0 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
275f0 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
27600 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
27610 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
27620 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
27630 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
27640 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
27650 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
27660 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
27670 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
27680 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
27690 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
276a0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
276b0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
276c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
276d0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
276e0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
276f0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
27700 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
27710 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
27720 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
27730 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
27740 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
27750 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
27760 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
27770 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
27780 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
27790 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
277a0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
277b0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
277c0 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
277d0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
277e0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
277f0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
27800 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
27810 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
27820 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
27830 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
27840 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
27850 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
27860 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
27870 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
27880 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
27890 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
278a0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
278b0 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
278c0 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
278d0 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
278e0 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
278f0 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49  nding}.**.** ^(I
27900 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
27910 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
27920 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
27930 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
27940 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
27950 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
27960 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
27970 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
27980 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
27990 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
279a0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
279b0 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
279c0 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
279d0 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
279e0 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
279f0 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
27a00 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
27a10 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
27a20 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
27a30 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
27a40 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
27a50 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
27a60 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
27a70 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
27a80 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
27a90 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
27aa0 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
27ab0 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
27ac0 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
27ad0 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
27ae0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
27af0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
27b00 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
27b10 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
27b20 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
27b30 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
27b40 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
27b50 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
27b60 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
27b70 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
27b80 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
27b90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
27ba0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
27bb0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
27bc0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
27bd0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
27be0 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
27bf0 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
27c00 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
27c10 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
27c20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
27c30 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
27c40 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
27c50 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
27c60 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
27c70 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
27c80 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
27c90 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
27ca0 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
27cb0 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
27cc0 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
27cd0 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
27ce0 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
27cf0 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
27d00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
27d10 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
27d20 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
27d30 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
27d40 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
27d50 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
27d60 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
27d70 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
27d80 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
27d90 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
27da0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
27db0 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
27dc0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
27dd0 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
27de0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
27df0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
27e00 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
27e10 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
27e20 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
27e30 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
27e40 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
27e50 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
27e60 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
27e70 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71  ext16().** or sq
27e80 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
27e90 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
27ea0 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ter then the fou
27eb0 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rth parameter.**
27ec0 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20   is ignored and 
27ed0 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69  the end result i
27ee0 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71  s the same as sq
27ef0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
27f00 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  )..**.** ^(In th
27f10 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
27f20 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
27f30 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
27f40 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
27f50 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
27f60 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
27f70 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
27f80 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
27f90 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
27fa0 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
27fb0 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
27fc0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
27fd0 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
27fe0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
27ff0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
28000 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
28010 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
28020 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  ().** is negativ
28030 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67  e, then the leng
28040 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
28050 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
28060 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
28070 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
28080 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49  terminator..** I
28090 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
280a0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
280b0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
280c0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a   negative, then.
280d0 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ** the behavior 
280e0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
280f0 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69   If a non-negati
28100 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ve fourth parame
28110 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20  ter is provided 
28120 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
28130 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  text().** or sql
28140 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
28150 28 29 20 74 68 65 6e 20 74 68 61 74 20 70 61 72  () then that par
28160 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
28170 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
28180 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
28190 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
281a0 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
281b0 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
281c0 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
281d0 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
281e0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
281f0 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
28200 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
28210 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
28220 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
28230 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
28240 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
28250 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
28260 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
28270 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
28280 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
28290 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
282a0 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
282b0 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
282c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
282d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
282e0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
282f0 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
28300 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
28310 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
28320 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
28330 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
28340 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
28350 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
28360 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
28370 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
28380 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
28390 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
283a0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
283b0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
283c0 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
283d0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
283e0 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  blob(),.** sqlit
283f0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
28400 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
28410 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20  text16() fails. 
28420 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66   .** ^If the fif
28430 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
28440 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
28450 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
28460 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
28470 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
28480 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
28490 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
284a0 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
284b0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
284c0 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
284d0 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
284e0 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
284f0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
28500 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
28510 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
28520 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
28530 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
28540 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
28550 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
28560 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
28570 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
28580 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28590 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
285a0 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
285b0 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
285c0 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
285d0 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
285e0 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
285f0 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
28600 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
28610 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
28620 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
28630 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
28640 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
28650 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
28660 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
28670 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
28680 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
28690 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
286a0 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
286b0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
286c0 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
286d0 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
286e0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
286f0 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
28700 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
28710 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
28720 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
28730 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
28740 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
28750 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
28760 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
28770 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
28780 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
28790 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
287a0 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
287b0 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
287c0 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
287d0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
287e0 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
287f0 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
28800 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
28810 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
28820 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
28830 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
28840 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
28850 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
28860 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
28870 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28880 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
28890 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
288a0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
288b0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
288c0 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
288d0 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
288e0 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
288f0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
28900 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
28910 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
28920 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
28930 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
28940 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28950 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
28960 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
28970 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
28980 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
28990 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
289a0 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
289b0 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
289c0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
289d0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
289e0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
289f0 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
28a00 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
28a10 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
28a20 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
28a30 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
28a40 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
28a50 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
28a60 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
28a70 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
28a80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
28a90 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
28aa0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
28ab0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
28ac0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
28ad0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
28ae0 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
28af0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
28b00 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
28b10 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
28b20 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
28b30 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53   int, double);.S
28b40 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
28b50 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
28b60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28b70 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t, int);.SQLITE_
28b80 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
28b90 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
28ba0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
28bb0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53  qlite3_int64);.S
28bc0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
28bd0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
28be0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28bf0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
28c00 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
28c10 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
28c20 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
28c30 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
28c40 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
28c50 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
28c60 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
28c70 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
28c80 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
28c90 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
28ca0 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
28cb0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
28cc0 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
28cd0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
28ce0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
28cf0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
28d00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
28d10 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
28d20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
28d30 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
28d40 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
28d50 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
28d60 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
28d70 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
28d80 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
28d90 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
28da0 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
28db0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28dc0 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
28dd0 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
28de0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
28df0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
28e00 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
28e10 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
28e20 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
28e30 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
28e40 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
28e50 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
28e60 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
28e70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
28e80 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
28e90 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
28ea0 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
28eb0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
28ec0 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
28ed0 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
28ee0 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
28ef0 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
28f00 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
28f10 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
28f20 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
28f30 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
28f40 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
28f50 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
28f60 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
28f70 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
28f80 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
28f90 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
28fa0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
28fb0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
28fc0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
28fd0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
28fe0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
28ff0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29000 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
29010 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
29020 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29030 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
29040 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
29050 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
29060 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
29070 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  er.**.** ^The sq
29080 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29090 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
290a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
290b0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
290c0 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
290d0 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
290e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
290f0 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
29100 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
29110 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
29120 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
29130 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
29140 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
29150 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
29160 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
29170 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
29180 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
29190 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
291a0 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
291b0 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
291c0 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
291d0 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
291e0 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
291f0 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
29200 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
29210 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
29220 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
29230 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
29240 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
29250 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
29260 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
29270 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
29280 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
29290 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
292a0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
292b0 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
292c0 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
292d0 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
292e0 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
292f0 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
29300 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
29310 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
29320 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
29330 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
29340 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
29350 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
29360 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
29370 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
29380 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
29390 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
293a0 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
293b0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
293c0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
293d0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
293e0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
293f0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
29400 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
29410 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
29420 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
29430 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29440 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
29450 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
29460 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
29470 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
29480 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
29490 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
294a0 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
294b0 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
294c0 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
294d0 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
294e0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
294f0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
29500 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
29510 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
29520 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
29530 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
29540 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
29550 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
29560 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
29570 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
29580 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
29590 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
295a0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
295b0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
295c0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
295d0 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
295e0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
295f0 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
29600 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
29610 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
29620 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
29630 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29640 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
29650 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
29660 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
29670 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
29680 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
29690 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
296a0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
296b0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
296c0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
296d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
296e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
296f0 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
29700 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
29710 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
29720 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29730 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
29740 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
29750 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
29760 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
29770 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
29780 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
29790 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
297a0 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
297b0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
297c0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
297d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
297e0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
297f0 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
29800 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
29810 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
29820 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
29830 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
29840 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
29850 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
29860 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
29870 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
29880 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
29890 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
298a0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
298b0 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
298c0 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
298d0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
298e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
298f0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
29900 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
29910 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
29920 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
29930 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
29940 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
29950 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
29960 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
29970 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
29980 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
29990 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
299a0 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
299b0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
299c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
299d0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
299e0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
299f0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
29a00 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
29a10 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
29a20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
29a30 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
29a40 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
29a50 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
29a60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
29a70 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
29a80 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
29a90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
29aa0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
29ab0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
29ac0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
29ad0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
29ae0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
29af0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
29b00 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
29b10 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
29b20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
29b30 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29b40 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
29b50 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
29b60 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
29b70 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
29b80 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
29b90 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
29ba0 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
29bb0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
29bc0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
29bd0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
29be0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
29bf0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
29c00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29c10 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
29c20 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
29c30 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
29c40 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
29c50 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
29c60 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
29c70 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
29c80 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
29c90 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
29ca0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
29cb0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
29cc0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
29cd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
29ce0 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
29cf0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
29d00 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
29d10 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
29d20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
29d30 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
29d40 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
29d50 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
29d60 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
29d70 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
29d80 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
29d90 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
29da0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
29db0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
29dc0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
29dd0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
29de0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
29df0 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
29e00 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
29e10 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
29e20 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
29e30 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
29e40 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
29e50 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
29e60 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
29e70 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
29e80 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
29e90 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
29ea0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
29eb0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
29ec0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
29ed0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
29ee0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
29ef0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
29f00 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
29f10 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
29f20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29f30 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
29f40 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
29f50 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
29f60 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
29f70 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
29f80 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
29f90 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
29fa0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
29fb0 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
29fc0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
29fd0 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
29fe0 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
29ff0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
2a000 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
2a010 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2a020 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
2a030 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
2a040 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
2a050 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
2a060 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
2a070 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
2a080 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
2a090 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
2a0a0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
2a0b0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
2a0c0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
2a0d0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
2a0e0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
2a0f0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2a100 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
2a110 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2a120 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
2a130 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
2a140 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
2a150 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
2a160 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2a170 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2a180 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2a190 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2a1a0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2a1b0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2a1c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2a1d0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2a1e0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2a1f0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
2a200 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
2a210 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
2a220 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
2a230 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
2a240 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
2a250 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
2a260 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
2a270 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
2a280 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2a290 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
2a2a0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2a2b0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
2a2c0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
2a2d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a2e0 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
2a2f0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2a300 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2a310 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
2a320 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
2a330 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
2a340 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
2a350 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2a360 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2a370 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
2a380 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
2a390 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
2a3a0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
2a3b0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2a3c0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
2a3d0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2a3e0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
2a3f0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
2a400 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
2a410 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
2a420 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2a430 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
2a440 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
2a450 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
2a460 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
2a470 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2a480 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
2a490 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
2a4a0 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
2a4b0 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
2a4c0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
2a4d0 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
2a4e0 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
2a4f0 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
2a500 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
2a510 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
2a520 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
2a530 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
2a540 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
2a550 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
2a560 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
2a570 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
2a580 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
2a590 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
2a5a0 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
2a5b0 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
2a5c0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
2a5d0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2a5e0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
2a5f0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
2a600 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
2a610 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
2a620 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2a630 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2a640 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
2a650 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2a660 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
2a670 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
2a680 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
2a690 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
2a6a0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2a6b0 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
2a6c0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
2a6d0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2a6e0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2a6f0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
2a700 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2a710 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
2a720 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
2a730 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
2a740 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
2a750 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
2a760 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
2a770 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2a780 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2a790 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2a7a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2a7b0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2a7c0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2a7d0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2a7e0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2a7f0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2a800 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2a810 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
2a820 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2a830 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2a840 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2a850 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2a860 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2a870 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2a880 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2a890 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2a8a0 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
2a8b0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2a8c0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2a8d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2a8e0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2a8f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2a900 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2a910 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2a920 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2a930 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2a940 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2a950 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2a960 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
2a970 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
2a980 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
2a990 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2a9a0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2a9b0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
2a9c0 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
2a9d0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
2a9e0 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
2a9f0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
2aa00 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
2aa10 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
2aa20 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
2aa30 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
2aa40 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
2aa50 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
2aa60 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
2aa70 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
2aa80 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
2aa90 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
2aaa0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2aab0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2aac0 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
2aad0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
2aae0 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
2aaf0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
2ab00 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
2ab10 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
2ab20 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
2ab30 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
2ab40 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
2ab50 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2ab60 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
2ab70 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
2ab80 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
2ab90 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
2aba0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
2abb0 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
2abc0 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
2abd0 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
2abe0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
2abf0 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
2ac00 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
2ac10 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
2ac20 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
2ac30 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
2ac40 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
2ac50 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
2ac60 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
2ac70 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
2ac80 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
2ac90 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
2aca0 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
2acb0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
2acc0 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
2acd0 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
2ace0 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
2acf0 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
2ad00 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
2ad10 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
2ad20 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
2ad30 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
2ad40 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
2ad50 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
2ad60 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
2ad70 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
2ad80 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2ad90 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
2ada0 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
2adb0 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
2adc0 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
2add0 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c  e values..*/.SQL
2ade0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2adf0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2ae00 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
2ae10 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2ae20 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2ae30 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2ae40 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
2ae50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2ae60 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2ae70 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
2ae80 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
2ae90 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
2aea0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2aeb0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
2aec0 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
2aed0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
2aee0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2aef0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2af00 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
2af10 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
2af20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
2af30 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
2af40 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2af50 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
2af60 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
2af70 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
2af80 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
2af90 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
2afa0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
2afb0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
2afc0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
2afd0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
2afe0 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
2aff0 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
2b000 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
2b010 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
2b020 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
2b030 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
2b040 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2b050 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2b060 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
2b070 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
2b080 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
2b090 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2b0a0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2b0b0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
2b0c0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
2b0d0 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
2b0e0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2b0f0 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
2b100 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
2b110 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2b120 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
2b130 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
2b140 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
2b150 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2b160 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
2b170 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
2b180 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
2b190 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
2b1a0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
2b1b0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2b1c0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
2b1d0 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
2b1e0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2b1f0 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
2b200 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
2b210 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
2b220 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
2b230 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2b240 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
2b250 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
2b260 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2b270 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
2b280 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
2b290 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
2b2a0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
2b2b0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
2b2c0 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
2b2d0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
2b2e0 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
2b2f0 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
2b300 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
2b310 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
2b320 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
2b330 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
2b340 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2b350 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
2b360 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
2b370 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
2b380 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
2b390 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
2b3a0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
2b3b0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
2b3c0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
2b3d0 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
2b3e0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
2b3f0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
2b400 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
2b410 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
2b420 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2b430 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2b440 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
2b450 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
2b460 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
2b470 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
2b480 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
2b490 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
2b4a0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
2b4b0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
2b4c0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
2b4d0 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
2b4e0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
2b4f0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
2b500 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
2b510 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
2b520 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
2b530 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
2b540 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
2b550 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
2b560 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
2b570 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
2b580 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
2b590 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
2b5a0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
2b5b0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2b5c0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
2b5d0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
2b5e0 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
2b5f0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2b600 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
2b610 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
2b620 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
2b630 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
2b640 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
2b650 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
2b660 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2b670 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2b680 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
2b690 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
2b6a0 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
2b6b0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2b6c0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
2b6d0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
2b6e0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
2b6f0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2b700 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
2b710 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
2b720 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
2b730 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
2b740 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
2b750 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
2b760 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
2b770 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2b780 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
2b790 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2b7a0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
2b7b0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2b7c0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
2b7d0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2b7e0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
2b7f0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
2b800 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
2b810 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
2b820 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
2b830 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
2b840 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
2b850 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
2b860 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
2b870 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
2b880 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2b890 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
2b8a0 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
2b8b0 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
2b8c0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
2b8d0 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
2b8e0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
2b8f0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
2b900 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
2b910 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
2b920 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
2b930 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
2b940 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2b950 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
2b960 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
2b970 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
2b980 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
2b990 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
2b9a0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
2b9b0 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
2b9c0 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
2b9d0 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
2b9e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2b9f0 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
2ba00 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
2ba10 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
2ba20 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
2ba30 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
2ba40 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
2ba50 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
2ba60 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
2ba70 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
2ba80 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
2ba90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2baa0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
2bab0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
2bac0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
2bad0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
2bae0 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
2baf0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
2bb00 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
2bb10 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
2bb20 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
2bb30 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
2bb40 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
2bb50 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
2bb60 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
2bb70 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
2bb80 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
2bb90 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
2bba0 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
2bbb0 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
2bbc0 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
2bbd0 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
2bbe0 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
2bbf0 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
2bc00 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
2bc10 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
2bc20 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
2bc30 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
2bc40 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
2bc50 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
2bc60 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
2bc70 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
2bc80 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
2bc90 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
2bca0 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
2bcb0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2bcc0 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
2bcd0 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
2bce0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
2bcf0 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
2bd00 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
2bd10 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
2bd20 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
2bd30 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
2bd40 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
2bd50 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
2bd60 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
2bd70 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2bd80 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2bd90 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
2bda0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
2bdb0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
2bdc0 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
2bdd0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
2bde0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
2bdf0 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
2be00 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
2be10 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
2be20 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
2be30 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
2be40 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
2be50 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
2be60 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
2be70 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
2be80 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
2be90 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2bea0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2beb0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
2bec0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
2bed0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
2bee0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
2bef0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2bf00 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
2bf10 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
2bf20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2bf30 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
2bf40 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
2bf50 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
2bf60 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
2bf70 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2bf80 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
2bf90 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2bfa0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
2bfb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2bfc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bfd0 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
2bfe0 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
2bff0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
2c000 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2c010 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
2c020 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2c030 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2c040 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
2c050 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2c060 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
2c070 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
2c080 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
2c090 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
2c0a0 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
2c0b0 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
2c0c0 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
2c0d0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2c0e0 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
2c0f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
2c100 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
2c110 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
2c120 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
2c130 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
2c140 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2c150 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
2c160 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
2c170 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
2c180 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
2c190 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2c1a0 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
2c1b0 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
2c1c0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
2c1d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
2c1e0 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
2c1f0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
2c200 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2c210 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
2c220 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
2c230 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
2c240 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2c250 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
2c260 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
2c270 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
2c280 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
2c290 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
2c2a0 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
2c2b0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2c2c0 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
2c2d0 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
2c2e0 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
2c2f0 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
2c300 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
2c310 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2c320 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2c330 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nt()].*/.SQLITE_
2c340 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2c350 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
2c360 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2c370 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c380 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
2c390 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
2c3a0 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
2c3b0 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
2c3c0 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
2c3d0 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
2c3e0 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
2c3f0 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
2c400 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2c410 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2c420 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
2c430 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
2c440 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
2c450 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
2c460 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
2c470 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
2c480 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2c490 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
2c4a0 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
2c4b0 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
2c4c0 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
2c4d0 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
2c4e0 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
2c4f0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2c500 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
2c510 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
2c520 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
2c530 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
2c540 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
2c550 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
2c560 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
2c570 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
2c580 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
2c590 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
2c5a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2c5b0 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
2c5c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
2c5d0 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
2c5e0 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
2c5f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c600 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
2c610 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
2c620 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
2c630 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
2c640 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
2c650 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
2c660 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
2c670 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
2c680 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
2c690 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
2c6a0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
2c6b0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2c6c0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
2c6d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
2c6e0 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65  m the "result se
2c6f0 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  t" interface..**
2c700 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2c710 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
2c720 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
2c730 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
2c740 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
2c750 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
2c760 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
2c770 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
2c780 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
2c790 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
2c7a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c7b0 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
2c7c0 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
2c7d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
2c7e0 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
2c7f0 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
2c800 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2c810 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
2c820 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
2c830 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
2c840 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2c850 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
2c860 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
2c870 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
2c880 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
2c890 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2c8a0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2c8b0 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
2c8c0 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
2c8d0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2c8e0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
2c8f0 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
2c900 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2c910 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2c920 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
2c930 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
2c940 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
2c950 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
2c960 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
2c970 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
2c980 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2c990 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
2c9a0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
2c9b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
2c9c0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
2c9d0 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
2c9e0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
2c9f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2ca00 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
2ca10 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
2ca20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2ca30 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
2ca40 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2ca50 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
2ca60 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
2ca70 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
2ca80 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2ca90 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
2caa0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2cab0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2cac0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2cad0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2cae0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
2caf0 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
2cb00 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
2cb10 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
2cb20 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2cb30 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
2cb40 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
2cb50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2cb60 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2cb70 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
2cb80 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
2cb90 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
2cba0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
2cbb0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
2cbc0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
2cbd0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2cbe0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2cbf0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2cc00 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
2cc10 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2cc20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2cc30 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
2cc40 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
2cc50 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
2cc60 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
2cc70 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
2cc80 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
2cc90 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
2cca0 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
2ccb0 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
2ccc0 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
2ccd0 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
2cce0 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
2ccf0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
2cd00 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2cd10 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
2cd20 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
2cd30 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
2cd40 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
2cd50 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
2cd60 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
2cd70 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
2cd80 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
2cd90 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
2cda0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2cdb0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
2cdc0 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
2cdd0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2cde0 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
2cdf0 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
2ce00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2ce10 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
2ce20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
2ce30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2ce40 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2ce50 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
2ce60 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2ce70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
2ce80 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2ce90 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2cea0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2ceb0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2cec0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2ced0 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
2cee0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
2cef0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2cf00 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2cf10 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
2cf20 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
2cf30 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2cf40 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
2cf50 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
2cf60 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
2cf70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cf80 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
2cf90 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2cfa0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2cfb0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2cfc0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
2cfd0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2cfe0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2cff0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
2d000 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2d010 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2d020 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d030 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
2d040 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
2d050 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
2d060 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
2d070 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2d080 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d090 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
2d0a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2d0b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2d0c0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2d0d0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2d0e0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
2d0f0 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
2d100 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d110 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
2d120 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2d130 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
2d140 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2d150 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2d160 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2d170 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2d180 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2d190 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2d1a0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2d1b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2d1c0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2d1d0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
2d1e0 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
2d1f0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2d200 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2d210 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2d220 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2d230 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2d240 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d250 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
2d260 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
2d270 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
2d280 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2d290 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
2d2a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2d2b0 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
2d2c0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
2d2d0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
2d2e0 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
2d2f0 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
2d300 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
2d310 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2d320 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2d330 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
2d340 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
2d350 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
2d360 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
2d370 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
2d380 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
2d390 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2d3a0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
2d3b0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
2d3c0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2d3d0 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
2d3e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2d3f0 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
2d400 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
2d410 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
2d420 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
2d430 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
2d440 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
2d450 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
2d460 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
2d470 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2d480 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62  r..**.** ^The ob
2d490 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2d4a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2d4b0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
2d4c0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2d4d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2d4e0 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f  bject.  An unpro
2d4f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d500 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d  alue object.** m
2d510 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2d520 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69  with [sqlite3_bi
2d530 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
2d540 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2d550 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
2d560 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
2d570 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2d580 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2d590 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2d5a0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2d5b0 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
2d5c0 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
2d5d0 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
2d5e0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
2d5f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2d600 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2d610 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
2d620 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
2d630 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20  _bytes()], then 
2d640 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2d650 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2d660 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2d670 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
2d680 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
2d690 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
2d6a0 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
2d6b0 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
2d6c0 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
2d6d0 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
2d6e0 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
2d6f0 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
2d700 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2d710 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
2d720 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
2d730 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
2d740 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
2d750 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
2d760 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
2d770 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
2d780 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
2d790 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
2d7a0 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
2d7b0 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
2d7c0 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
2d7d0 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
2d7e0 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
2d7f0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
2d800 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
2d810 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2d820 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
2d830 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
2d840 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2d850 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2d860 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
2d870 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
2d880 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
2d890 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
2d8a0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
2d8b0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
2d8c0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
2d8d0 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
2d8e0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
2d8f0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2d900 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
2d910 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
2d920 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
2d930 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
2d940 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2d950 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2d960 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
2d970 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
2d980 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2d990 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
2d9a0 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
2d9b0 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
2d9c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2d9d0 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
2d9e0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
2d9f0 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69   from float to i
2da00 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
2da10 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2da20 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2da30 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
2da40 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
2da50 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2da60 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2da70 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c   <td> Same as FL
2da80 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  OAT->TEXT.** <tr
2da90 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2daa0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2dab0 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a  d> Use atoi().**
2dac0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2dad0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2dae0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28    <td> Use atof(
2daf0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
2db00 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
2db10 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
2db20 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
2db30 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
2db40 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
2db50 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
2db60 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a  en use atoi().**
2db70 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2db80 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2db90 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
2dba0 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
2dbb0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
2dbc0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2dbd0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2dbe0 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
2dbf0 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
2dc00 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
2dc10 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
2dc20 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
2dc30 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
2dc40 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
2dc50 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
2dc60 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
2dc70 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
2dc80 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
2dc90 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
2dca0 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
2dcb0 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76  its.** own equiv
2dcc0 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
2dcd0 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
2dce0 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
2dcf0 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
2dd00 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
2dd10 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
2dd20 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
2dd30 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
2dd40 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
2dd50 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2dd60 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
2dd70 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
2dd80 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2dd90 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
2dda0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2ddb0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
2ddc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2ddd0 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
2dde0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2ddf0 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
2de00 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
2de10 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
2de20 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
2de30 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
2de40 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
2de50 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
2de60 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2de70 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2de80 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
2de90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2dea0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
2deb0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2dec0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2ded0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
2dee0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
2def0 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
2df00 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
2df10 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
2df20 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2df30 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
2df40 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
2df50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2df60 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
2df70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2df80 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2df90 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2dfa0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2dfb0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2dfc0 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
2dfd0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2dfe0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
2dff0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2e000 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2e010 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2e020 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2e030 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2e040 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2e050 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2e060 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
2e070 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2e080 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
2e090 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
2e0a0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
2e0b0 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
2e0c0 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
2e0d0 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
2e0e0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
2e0f0 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
2e100 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2e110 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
2e120 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
2e130 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
2e140 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
2e150 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
2e160 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
2e170 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
2e180 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
2e190 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
2e1a0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
2e1b0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
2e1c0 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
2e1d0 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
2e1e0 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
2e1f0 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
2e200 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
2e210 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
2e220 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
2e230 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
2e240 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
2e250 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
2e260 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
2e270 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2e280 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
2e290 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2e2a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2e2b0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2e2c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2e2d0 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
2e2e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e2f0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
2e300 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2e310 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
2e320 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2e330 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2e340 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
2e350 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
2e360 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
2e370 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
2e380 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
2e390 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2e3a0 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
2e3b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2e3c0 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
2e3d0 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
2e3e0 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
2e3f0 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
2e400 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
2e410 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
2e420 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e430 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
2e440 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
2e450 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
2e460 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
2e470 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e480 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2e490 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2e4a0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
2e4b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e4c0 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
2e4d0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
2e4e0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2e4f0 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
2e500 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
2e510 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e520 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
2e530 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2e540 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
2e550 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2e560 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
2e570 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
2e580 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
2e590 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
2e5a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2e5b0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2e5c0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
2e5d0 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
2e5e0 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
2e5f0 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
2e600 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
2e610 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
2e620 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
2e630 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
2e640 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
2e650 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e660 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
2e670 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
2e680 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
2e690 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
2e6a0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
2e6b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2e6c0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2e6d0 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
2e6e0 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
2e6f0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
2e700 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
2e710 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
2e720 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
2e730 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
2e740 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
2e750 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2e760 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
2e770 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
2e780 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
2e790 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
2e7a0 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
2e7b0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
2e7c0 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51  _NOMEM].)^.*/.SQ
2e7d0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2e7e0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2e7f0 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
2e800 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2e810 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2e820 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2e830 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
2e840 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2e850 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2e860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e870 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
2e880 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2e890 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62  .SQLITE_API doub
2e8a0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
2e8b0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
2e8c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2e8d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2e8e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2e8f0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2e900 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
2e910 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
2e920 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
2e930 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
2e940 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2e950 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
2e960 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  I const unsigned
2e970 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2e980 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
2e990 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2e9a0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2e9b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2e9c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2e9d0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2e9e0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2e9f0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2ea00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
2ea10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ea20 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
2ea30 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  API sqlite3_valu
2ea40 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
2ea50 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
2ea60 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2ea70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ea80 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
2ea90 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2eaa0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Object.**.** ^Th
2eab0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
2eac0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
2ead0 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
2eae0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
2eaf0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66  atement]..** ^If
2eb00 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2eb10 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74   evaluation of t
2eb20 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63  he statement enc
2eb30 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f  ountered no erro
2eb40 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20  rs.** or if the 
2eb50 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76  statement is nev
2eb60 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65  er been evaluate
2eb70 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  d, then sqlite3_
2eb80 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72  finalize() retur
2eb90 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e  ns.** SQLITE_OK.
2eba0 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72    ^If the most r
2ebb0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
2ebc0 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20   of statement S 
2ebd0 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  failed, then.** 
2ebe0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ebf0 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (S) returns the 
2ec00 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
2ec10 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  or code] or.** [
2ec20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
2ec30 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
2ec40 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2ec50 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e  e(S) routine can
2ec60 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
2ec70 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a  y point during.*
2ec80 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65  * the life cycle
2ec90 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
2eca0 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62  atement] S:.** b
2ecb0 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20  efore statement 
2ecc0 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61  S is ever evalua
2ecd0 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e  ted, after.** on
2ece0 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20  e or more calls 
2ecf0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
2ed00 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61  t()], or after a
2ed10 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73  ny call.** to [s
2ed20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
2ed30 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
2ed40 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
2ed50 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a  statement has.**
2ed60 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
2ed70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76  tion..**.** ^Inv
2ed80 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69  oking sqlite3_fi
2ed90 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55  nalize() on a NU
2eda0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20  LL pointer is a 
2edb0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
2edc0 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
2edd0 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c  ation must final
2ede0 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61  ize every [prepa
2edf0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
2ee00 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64  n order to avoid
2ee10 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61  .** resource lea
2ee20 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69  ks.  It is a gri
2ee30 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20  evous error for 
2ee40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2ee50 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a  to try to use.**
2ee60 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2ee70 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
2ee80 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2ee90 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61  d.  Any use of a
2eea0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2eeb0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
2eec0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2eed0 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  ed can result in
2eee0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a   undefined and.*
2eef0 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  * undesirable be
2ef00 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73  havior such as s
2ef10 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61  egfaults and hea
2ef20 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  p corruption..*/
2ef30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ef40 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ef50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2ef60 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2ef70 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
2ef80 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2ef90 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
2efa0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
2efb0 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
2efc0 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
2efd0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2efe0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
2eff0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
2f000 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
2f010 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
2f020 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
2f030 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
2f040 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
2f050 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
2f060 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
2f070 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2f080 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
2f090 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
2f0a0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
2f0b0 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
2f0c0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
2f0d0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
2f0e0 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
2f0f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2f100 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
2f110 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
2f120 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f130 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
2f140 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
2f150 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
2f160 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2f170 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2f180 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2f190 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2f1a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f1b0 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
2f1c0 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
2f1d0 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
2f1e0 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
2f1f0 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
2f200 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
2f210 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
2f220 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2f230 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
2f240 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
2f250 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2f260 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2f270 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2f280 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2f290 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2f2a0 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
2f2b0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
2f2c0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
2f2d0 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
2f2e0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
2f2f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
2f300 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2f310 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
2f320 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
2f330 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
2f340 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2f350 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
2f360 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2f370 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51  tement] S..*/.SQ
2f380 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2f390 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
2f3a0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2f3b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f3c0 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
2f3d0 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
2f3e0 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
2f3f0 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  {function creati
2f400 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20  on routines}.** 
2f410 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
2f420 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2f430 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20  QL function}.** 
2f440 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
2f450 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2f460 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  QL functions}.**
2f470 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
2f480 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65  ions (collective
2f490 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e  ly known as "fun
2f4a0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
2f4b0 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65  outines").** are
2f4c0 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
2f4d0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2f4e0 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72  gregates or to r
2f4f0 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
2f500 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74  vior.** of exist
2f510 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
2f520 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
2f530 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65    The only diffe
2f540 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a  rences between.*
2f550 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * these routines
2f560 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e   are the text en
2f570 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20  coding expected 
2f580 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  for.** the secon
2f590 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  d parameter (the
2f5a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e   name of the fun
2f5b0 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61  ction being crea
2f5c0 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ted).** and the 
2f5d0 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65  presence or abse
2f5e0 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63  nce of a destruc
2f5f0 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72  tor callback for
2f600 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
2f610 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
2f620 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2f630 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2f640 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2f650 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69  nnection] to whi
2f660 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  ch the SQL.** fu
2f670 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  nction is to be 
2f680 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61  added.  ^If an a
2f690 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20  pplication uses 
2f6a0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61  more than one da
2f6b0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
2f6c0 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63  tion then applic
2f6d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2f6e0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74  L functions must
2f6f0 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20   be added.** to 
2f700 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
2f710 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74  nnection separat
2f720 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ely..**.** ^The 
2f730 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2f740 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
2f750 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2f760 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f   to be created o
2f770 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20  r.** redefined. 
2f780 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20   ^The length of 
2f790 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
2f7a0 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
2f7b0 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72   in a UTF-8.** r
2f7c0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65  epresentation, e
2f7d0 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
2f7e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
2f7f0 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65    ^Note that the
2f800 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20   name.** length 
2f810 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d  limit is in UTF-
2f820 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61  8 bytes, not cha
2f830 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d  racters nor UTF-
2f840 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e  16 bytes.  .** ^
2f850 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
2f860 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e  reate a function
2f870 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e   with a longer n
2f880 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75  ame.** will resu
2f890 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  lt in [SQLITE_MI
2f8a0 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75  SUSE] being retu
2f8b0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
2f8c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2f8d0 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68   (nArg).** is th
2f8e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
2f8f0 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53  ments that the S
2f900 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2f910 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65  * aggregate take
2f920 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61  s. ^If this para
2f930 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65  meter is -1, the
2f940 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  n the SQL functi
2f950 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2f960 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20  te may take any 
2f970 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2f980 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e  nts between 0 an
2f990 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73  d the limit.** s
2f9a0 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  et by [sqlite3_l
2f9b0 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49  imit]([SQLITE_LI
2f9c0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
2f9d0 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72  ]).  If the thir
2f9e0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  d.** parameter i
2f9f0 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f  s less than -1 o
2fa00 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  r greater than 1
2fa10 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  27 then the beha
2fa20 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66  vior is.** undef
2fa30 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2fa40 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2fa50 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
2fa60 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b  cifies what.** [
2fa70 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65  SQLITE_UTF8 | te
2fa80 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69  xt encoding] thi
2fa90 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  s SQL function p
2faa0 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74  refers for.** it
2fab0 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45  s parameters.  E
2fac0 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f  very SQL functio
2fad0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2fae0 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f   must be able to
2faf0 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54   work.** with UT
2fb00 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f  F-8, UTF-16le, o
2fb10 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74  r UTF-16be.  But
2fb20 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61   some implementa
2fb30 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20  tions may be.** 
2fb40 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77  more efficient w
2fb50 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67  ith one encoding
2fb60 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20   than another.  
2fb70 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ^An application 
2fb80 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71  may.** invoke sq
2fb90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2fba0 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ction() or sqlit
2fbb0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2fbc0 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a  on16() multiple.
2fbd0 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  ** times with th
2fbe0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2fbf0 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
2fc00 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65  nt values of eTe
2fc10 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20  xtRep..** ^When 
2fc20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2fc30 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2fc40 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
2fc50 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
2fc60 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
2fc70 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
2fc80 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
2fc90 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
2fca0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49  conversion..** I
2fcb0 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20  f there is only 
2fcc0 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65  a single impleme
2fcd0 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f  ntation which do
2fce0 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74  es not care what
2fcf0 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e   text.** encodin
2fd00 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  g is used, then 
2fd10 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
2fd20 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53  ent should be [S
2fd30 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a  QLITE_ANY]..**.*
2fd40 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
2fd50 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
2fd60 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
2fd70 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
2fd80 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
2fd90 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
2fda0 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
2fdb0 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
2fdc0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2fdd0 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
2fde0 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68  e sixth, seventh
2fdf0 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61   and eighth para
2fe00 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
2fe10 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
2fe20 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
2fe30 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
2fe40 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
2fe50 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
2fe60 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2fe70 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
2fe80 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
2fe90 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
2fea0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2feb0 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
2fec0 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
2fed0 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65  pointers must be
2fee0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
2fef0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
2ff00 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
2ff10 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
2ff20 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2ff30 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2ff40 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
2ff50 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
2ff60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73  NULL pointer mus
2ff70 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  t be passed for 
2ff80 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
2ff90 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
2ffa0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2ffb0 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
2ffc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66   NULL pointers f
2ffd0 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
2ffe0 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
2fff0 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ks..**.** ^(If t
30000 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  he ninth paramet
30010 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
30020 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
30030 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a  () is not NULL,.
30040 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65  ** then it is de
30050 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
30060 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
30070 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54  a pointer. .** T
30080 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
30090 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
300a0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  e function is de
300b0 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79  leted, either by
300c0 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f   being.** overlo
300d0 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65  aded or when the
300e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
300f0 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a  tion closes.)^.*
30100 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f  * ^The destructo
30110 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65  r is also invoke
30120 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  d if the call to
30130 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
30140 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
30150 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e   fails..** ^When
30160 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
30170 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
30180 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
30190 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a  is invoked, it.*
301a0 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69  * is passed a si
301b0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
301c0 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ich is a copy of
301d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
301e0 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65   data .** pointe
301f0 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
30200 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
30210 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
30220 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e  e_function_v2().
30230 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
30240 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
30250 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
30260 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
30270 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
30280 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
30290 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
302a0 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
302b0 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
302c0 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
302d0 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
302e0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
302f0 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
30300 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
30310 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
30320 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
30330 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
30340 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
30350 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
30360 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
30370 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
30380 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
30390 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
303a0 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
303b0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
303c0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
303d0 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
303e0 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
303f0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
30400 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
30410 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
30420 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
30430 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
30440 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
30450 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
30460 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
30470 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
30480 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
30490 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
304a0 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
304b0 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
304c0 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
304d0 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
304e0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
304f0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
30500 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
30510 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
30520 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
30530 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
30540 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
30550 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
30560 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
30570 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
30580 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ons..**.** ^An a
30590 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
305a0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
305b0 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
305c0 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
305d0 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
305e0 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
305f0 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
30600 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
30610 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
30620 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
30630 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
30640 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
30650 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
30660 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
30670 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
30680 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30690 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
306a0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
306b0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
306c0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
306d0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
306e0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
306f0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
30700 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30710 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
30720 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
30730 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
30740 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
30750 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
30760 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
30770 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
30780 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
30790 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
307a0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
307b0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
307c0 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
307d0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
307e0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
307f0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
30800 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
30810 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
30820 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
30830 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
30840 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
30850 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
30860 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
30870 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
30880 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
30890 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  t*).);.SQLITE_AP
308a0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
308b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
308c0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
308d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
308e0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
308f0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
30900 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
30910 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
30920 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
30930 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
30940 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
30950 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
30960 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30970 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
30980 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
30990 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
309a0 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64  ontext*),.  void
309b0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
309c0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
309d0 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
309e0 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
309f0 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
30a00 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
30a10 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
30a20 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
30a30 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
30a40 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
30a50 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
30a60 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
30a70 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
30a80 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
30a90 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
30aa0 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
30ab0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
30ac0 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
30ad0 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
30ae0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
30af0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
30b00 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
30b10 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
30b20 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30b30 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
30b40 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
30b50 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
30b60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
30b70 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
30b80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30b90 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
30ba0 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
30bb0 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
30bc0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
30bd0 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
30be0 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
30bf0 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
30c00 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
30c10 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
30c20 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
30c30 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
30c40 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
30c50 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
30c60 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
30c70 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
30c80 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
30c90 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
30ca0 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
30cb0 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
30cc0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
30cd0 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
30ce0 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68  g to tell you wh
30cf0 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
30d00 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
30d10 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
30d20 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
30d30 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
30d40 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
30d50 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
30d60 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
30d70 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
30d80 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
30d90 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
30da0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
30db0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
30dc0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
30dd0 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
30de0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
30df0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
30e00 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
30e10 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
30e20 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  D int sqlite3_gl
30e30 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
30e40 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  d);.SQLITE_API S
30e50 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
30e60 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
30e70 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
30e80 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  d);.SQLITE_API S
30e90 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
30ea0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
30eb0 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
30ec0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
30ed0 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20  int64,int),.    
30ee0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30ef0 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f    void*,sqlite3_
30f00 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
30f10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30f20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
30f30 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
30f40 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68   Values.**.** Th
30f50 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
30f60 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
30f70 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
30f80 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
30f90 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
30fa0 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
30fb0 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
30fc0 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
30fd0 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
30fe0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
30ff0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
31000 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
31010 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
31020 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
31030 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
31040 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
31050 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
31060 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
31070 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
31080 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
31090 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
310a0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
310b0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
310c0 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
310d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
310e0 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
310f0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
31100 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
31110 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
31120 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
31130 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
31140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31150 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
31160 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
31170 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
31180 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
31190 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
311a0 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
311b0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
311c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
311d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
311e0 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
311f0 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
31200 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31210 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
31220 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
31230 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
31240 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
31250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
31260 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
31270 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
31280 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
31290 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
312a0 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
312b0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
312c0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
312d0 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
312e0 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72  pt that  these r
312f0 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
31300 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
31310 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
31320 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
31330 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
31340 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
31350 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
31360 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
31370 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
31380 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
31390 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
313a0 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
313b0 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
313c0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
313d0 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
313e0 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
313f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
31400 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
31410 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
31420 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
31430 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
31440 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
31450 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
31460 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
31470 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
31480 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
31490 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
314a0 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
314b0 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
314c0 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
314d0 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
314e0 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
314f0 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
31500 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
31510 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
31520 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
31530 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
31540 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
31550 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
31560 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
31570 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
31580 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
31590 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
315a0 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
315b0 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
315c0 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
315d0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
315e0 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
315f0 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
31600 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
31610 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
31620 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
31630 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
31640 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
31650 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
31660 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
31670 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
31680 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
31690 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
316a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
316b0 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
316c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
316d0 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
316e0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
316f0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
31700 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
31710 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
31720 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
31730 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
31740 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
31750 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
31760 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
31770 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
31780 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
31790 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
317a0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
317b0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
317c0 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
317d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
317e0 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
317f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
31800 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
31810 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
31820 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
31830 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
31840 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
31850 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
31860 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
31870 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31880 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
31890 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
318a0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
318b0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
318c0 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
318d0 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
318e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
318f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
31900 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
31910 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31920 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
31930 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
31940 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
31950 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
31960 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75  LITE_API const u
31970 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
31980 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31990 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
319a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
319b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
319c0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
319d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
319e0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
319f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
31a00 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
31a10 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
31a20 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
31a30 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
31a40 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
31a50 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
31a60 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
31a70 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
31a80 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31a90 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
31aa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
31ab0 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
31ac0 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
31ad0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
31ae0 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
31af0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a  ction Context.**
31b00 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  .** Implementati
31b10 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
31b20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
31b30 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
31b40 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
31b50 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
31b60 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
31b70 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
31b80 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
31b90 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31ba0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
31bb0 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
31bc0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
31bd0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
31be0 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
31bf0 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
31c00 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
31c10 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
31c20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
31c30 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
31c40 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
31c50 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
31c60 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
31c70 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
31c80 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
31c90 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
31ca0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
31cb0 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
31cc0 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
31cd0 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
31ce0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
31cf0 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
31d00 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
31d10 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
31d20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
31d30 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
31d40 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
31d50 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
31d60 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
31d70 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
31d80 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
31d90 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
31da0 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
31db0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
31dc0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
31dd0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
31de0 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
31df0 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
31e00 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
31e10 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
31e20 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
31e30 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31e40 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
31e50 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
31e60 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
31e70 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
31e80 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
31e90 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
31ea0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
31eb0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
31ec0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a   NULL pointer .*
31ed0 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c  * when first cal
31ee0 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73  led if N is less
31ef0 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
31f00 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
31f10 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
31f20 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
31f30 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
31f40 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
31f50 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
31f60 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31f70 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
31f80 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
31f90 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
31fa0 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
31fb0 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
31fc0 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
31fd0 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
31fe0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
31ff0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
32000 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
32010 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
32020 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
32030 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
32040 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
32050 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20   allocation.)^  
32060 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61  Within the xFina
32070 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69  l callback, it i
32080 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73  s customary to s
32090 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c  et.** N=0 in cal
320a0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ls to sqlite3_ag
320b0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
320c0 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20  C,N) so that no 
320d0 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65  .** pointless me
320e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
320f0 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53   occur..**.** ^S
32100 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
32110 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65  lly frees the me
32120 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
32130 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  y .** sqlite3_ag
32140 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
32150 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  ) when the aggre
32160 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c  gate query concl
32170 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
32180 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
32190 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f  must be a copy o
321a0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
321b0 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
321c0 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
321d0 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
321e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
321f0 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72   to the xStep or
32200 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
32210 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
32220 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
32230 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
32240 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
32250 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
32260 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
32270 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
32280 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
32290 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
322a0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
322b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
322c0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
322d0 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
322e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
322f0 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
32300 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
32310 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
32320 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
32330 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
32340 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
32350 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
32360 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
32370 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
32380 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
32390 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
323a0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
323b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
323c0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
323d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
323e0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
323f0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
32400 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
32410 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
32420 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
32430 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
32440 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
32450 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
32460 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
32470 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
32480 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32490 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
324a0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
324b0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
324c0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
324d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
324e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
324f0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
32500 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
32510 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
32520 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
32530 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
32540 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
32550 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
32560 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
32570 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32580 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
32590 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
325a0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
325b0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
325c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
325d0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
325e0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
325f0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
32600 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
32610 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
32620 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  function..*/.SQL
32630 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20  ITE_API sqlite3 
32640 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
32650 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
32660 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
32670 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
32680 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
32690 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65  y Data.**.** The
326a0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  se functions may
326b0 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e   be used by (non
326c0 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c 20  -aggregate) SQL 
326d0 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
326e0 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
326f0 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
32700 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
32710 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
32720 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
32730 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
32740 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
32750 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
32760 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
32770 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
32780 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
32790 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
327a0 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
327b0 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70  erved.  An examp
327c0 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74  le.** of where t
327d0 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 65  his might be use
327e0 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75  ful is in a regu
327f0 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
32800 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  atching.** funct
32810 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
32820 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
32830 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
32840 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65  ion can be store
32850 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
32860 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
32870 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72   the pattern str
32880 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61  ing.  .** Then a
32890 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61  s long as the pa
328a0 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d  ttern string rem
328b0 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a  ains the same,.*
328c0 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72  * the compiled r
328d0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
328e0 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
328f0 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
32900 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
32910 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e  e same function.
32920 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32930 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
32940 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
32950 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
32960 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
32970 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74   associated by t
32980 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
32990 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f  uxdata() functio
329a0 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  n with the Nth a
329b0 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65  rgument.** value
329c0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
329d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
329e0 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20  tion. ^If there 
329f0 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a  is no metadata.*
32a00 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
32a10 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61  h the function a
32a20 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71  rgument, this sq
32a30 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
32a40 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  a() interface.**
32a50 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
32a60 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
32a70 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
32a80 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
32a90 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
32aa0 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 20 66   P as metadata f
32ab0 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
32ac0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
32ad0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32ae0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53  ed function.  ^S
32af0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
32b00 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
32b10 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72  t_auxdata(C,N) r
32b20 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65  eturn P from the
32b30 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20   most recent.** 
32b40 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32b50 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c  ata(C,N,P,X) cal
32b60 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74  l if the metadat
32b70 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64  a is still valid
32b80 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74   or.** NULL if t
32b90 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  he metadata has 
32ba0 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a  been discarded..
32bb0 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20 63  ** ^After each c
32bc0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
32bd0 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
32be0 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 20 6e  ,X) where X is n
32bf0 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69  ot NULL,.** SQLi
32c00 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
32c10 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75  he destructor fu
32c20 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61  nction X with pa
32c30 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c  rameter P exactl
32c40 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20  y.** once, when 
32c50 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
32c60 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51  discarded..** SQ
32c70 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
32c80 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 74 61  discard the meta
32c90 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65  data at any time
32ca0 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c  , including: <ul
32cb0 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74  >.** <li> when t
32cc0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
32cd0 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
32ce0 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a  ter changes, or.
32cf0 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71  ** <li> when [sq
32d00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
32d10 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
32d20 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
32d30 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
32d40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
32d50 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  or.** <li> when 
32d60 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32d70 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ata() is invoked
32d80 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61   again on the sa
32d90 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72  me parameter, or
32da0 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20  .** <li> during 
32db0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c  the original sql
32dc0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
32dd0 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d  () call when a m
32de0 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61  emory .**      a
32df0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
32e00 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a  occurs. </ul>)^.
32e10 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c  **.** Note the l
32e20 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61  ast bullet in pa
32e30 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64  rticular.  The d
32e40 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a  estructor X in .
32e50 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
32e60 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
32e70 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
32e80 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
32e90 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  ore the.** sqlit
32ea0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
32eb0 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20   interface even 
32ec0 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20  returns.  Hence 
32ed0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32ee0 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20  ata().** should 
32ef0 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74  be called near t
32f00 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75  he end of the fu
32f10 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
32f20 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a  ation and the.**
32f30 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
32f40 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
32f50 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65  not make any use
32f60 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73   of P after.** s
32f70 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
32f80 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 63 61  ta() has been ca
32f90 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  lled..**.** ^(In
32fa0 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
32fb0 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
32fc0 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
32fd0 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66  n calls for.** f
32fe0 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
32ff0 72 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70  rs that are comp
33000 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e  ile-time constan
33010 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69  ts, including li
33020 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
33030 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
33040 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73   and expressions
33050 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74   composed from t
33060 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a  he same.)^.**.**
33070 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
33080 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
33090 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
330a0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
330b0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
330c0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
330d0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
330e0 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
330f0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
33100 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53  text*, int N);.S
33110 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
33120 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
33130 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
33140 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
33150 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
33160 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
33170 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
33180 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
33190 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
331a0 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
331b0 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
331c0 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
331d0 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
331e0 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
331f0 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
33200 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
33210 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
33220 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
33230 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
33240 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
33250 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
33260 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
33270 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
33280 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
33290 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
332a0 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
332b0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
332c0 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
332d0 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
332e0 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
332f0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
33300 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
33310 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
33320 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
33330 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
33340 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
33350 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
33360 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
33370 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
33380 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
33390 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
333a0 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
333b0 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
333c0 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
333d0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  s..*/.typedef vo
333e0 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
333f0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
33400 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
33410 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
33420 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
33430 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
33440 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
33450 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
33460 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
33470 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
33480 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
33490 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
334a0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL Function.**
334b0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
334c0 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
334d0 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
334e0 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
334f0 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
33500 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
33510 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
33520 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
33530 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
33540 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
33550 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
33560 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
33570 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
33580 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
33590 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
335a0 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
335b0 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  [parameter bindi
335c0 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ng] family of.**
335d0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20   functions used 
335e0 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74  to bind values t
335f0 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
33600 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74  s in prepared st
33610 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66  atements..** Ref
33620 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70  er to the [SQL p
33630 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65  arameter] docume
33640 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
33650 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
33660 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
33670 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
33680 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
33690 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
336a0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
336b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
336c0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
336d0 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
336e0 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
336f0 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
33700 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
33710 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
33720 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
33730 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
33740 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
33750 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
33760 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
33770 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
33780 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
33790 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
337a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
337b0 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
337c0 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
337d0 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
337e0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
337f0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
33800 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
33810 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
33820 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
33830 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
33840 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
33850 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
33860 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
33870 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
33880 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
33890 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
338a0 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
338b0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
338c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
338d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
338e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
338f0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
33900 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
33910 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
33920 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
33930 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
33940 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  on..** ^SQLite u
33950 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
33960 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
33970 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
33980 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
33990 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
339a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
339b0 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
339c0 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
339d0 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51  or message.  ^SQ
339e0 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
339f0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
33a00 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
33a10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33a20 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
33a30 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74  . ^SQLite.** int
33a40 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69  erprets the stri
33a50 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
33a60 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
33a70 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
33a80 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64  tive.** byte ord
33a90 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69  er.  ^If the thi
33aa0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
33ab0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33ac0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
33ad0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33ae0 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
33af0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
33b00 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
33b10 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
33b20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
33b30 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
33b40 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
33b50 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
33b60 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
33b70 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
33b80 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
33b90 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
33ba0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
33bb0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
33bc0 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
33bd0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
33be0 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
33bf0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
33c00 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
33c10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33c20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
33c30 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
33c40 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
33c50 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
33c60 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
33c70 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
33c80 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
33c90 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
33ca0 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
33cb0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
33cc0 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
33cd0 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
33ce0 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
33cf0 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
33d00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33d10 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
33d20 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61  e() function cha
33d30 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63  nges the error c
33d40 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ode.** returned 
33d50 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72  by SQLite as a r
33d60 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f  esult of an erro
33d70 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  r in a function.
33d80 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a    ^By default,.*
33d90 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  * the error code
33da0 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   is SQLITE_ERROR
33db0 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74  .  ^A subsequent
33dc0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
33dd0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
33de0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
33df0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
33e00 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
33e10 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
33e20 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  RROR..**.** ^The
33e30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33e40 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69  error_toobig() i
33e50 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
33e60 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
33e70 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
33e80 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
33e90 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
33ea0 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72  too long to repr
33eb0 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  esent..**.** ^Th
33ec0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33ed0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69  _error_nomem() i
33ee0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
33ef0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
33f00 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
33f10 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
33f20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
33f30 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
33f40 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33f50 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
33f60 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
33f70 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
33f80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
33f90 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
33fa0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
33fb0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
33fc0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
33fd0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
33fe0 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
33ff0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
34000 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
34010 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
34020 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
34030 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34040 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
34050 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
34060 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
34070 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
34080 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
34090 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
340a0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
340b0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
340c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
340d0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
340e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
340f0 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
34100 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34110 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
34120 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
34130 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
34140 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34150 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
34160 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34170 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
34180 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
34190 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
341a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
341b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
341c0 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
341d0 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
341e0 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
341f0 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
34200 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
34210 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
34220 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
34230 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
34240 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
34250 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
34260 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
34270 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
34280 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
34290 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
342a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
342b0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
342c0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
342d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
342e0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
342f0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
34300 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
34310 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
34320 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
34330 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
34340 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
34350 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
34360 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
34370 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
34380 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
34390 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
343a0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
343b0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
343c0 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
343d0 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
343e0 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
343f0 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
34400 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
34410 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
34420 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
34430 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
34440 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49  ction result.  I
34450 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
34460 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  ter is non-negat
34470 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20  ive, then it.** 
34480 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
34490 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65   offset into the
344a0 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68   string where th
344b0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
344c0 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72   would.** appear
344d0 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77   if the string w
344e0 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61  here NUL termina
344f0 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
34500 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
34510 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69  r.** in the stri
34520 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66  ng at a byte off
34530 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73  set that is less
34540 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20   than the value 
34550 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61  of the 3rd.** pa
34560 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
34570 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
34580 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20  ng will contain 
34590 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e  embedded NULs an
345a0 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  d the.** result 
345b0 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f  of expressions o
345c0 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69  perating on stri
345d0 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65  ngs with embedde
345e0 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
345f0 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
34600 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
34610 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
34620 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
34630 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
34640 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
34650 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
34660 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
34670 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
34680 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
34690 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
346a0 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
346b0 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
346c0 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
346d0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
346e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
346f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
34700 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34710 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
34720 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
34730 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
34740 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
34750 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
34760 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
34770 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
34780 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
34790 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
347a0 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
347b0 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
347c0 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
347d0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
347e0 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
347f0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
34800 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
34810 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
34820 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
34830 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
34840 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
34850 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34860 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
34870 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
34880 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
34890 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
348a0 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
348b0 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
348c0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
348d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
348e0 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
348f0 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
34900 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
34910 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
34920 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
34930 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
34940 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
34950 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
34960 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
34970 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34980 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
34990 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
349a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
349b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
349c0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
349d0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
349e0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
349f0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
34a00 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
34a10 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
34a20 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
34a30 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
34a40 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
34a50 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
34a60 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
34a70 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
34a80 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
34a90 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
34aa0 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
34ab0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
34ac0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
34ad0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
34ae0 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
34af0 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
34b00 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
34b10 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34b20 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
34b30 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
34b40 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
34b50 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
34b60 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
34b70 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
34b80 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
34b90 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
34ba0 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
34bb0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
34bc0 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
34bd0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
34be0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34bf0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
34c00 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
34c10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
34c20 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
34c30 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
34c40 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  fined..*/.SQLITE
34c50 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
34c60 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
34c70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34c80 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
34c90 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
34ca0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
34cb0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34cc0 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
34cd0 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
34ce0 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  e);.SQLITE_API v
34cf0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34d00 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
34d10 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
34d20 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51   char*, int);.SQ
34d30 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
34d40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34d50 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
34d60 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
34d70 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  d*, int);.SQLITE
34d80 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
34d90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
34da0 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
34db0 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
34dc0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
34dd0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
34de0 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
34df0 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
34e00 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
34e10 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
34e20 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34e30 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
34e40 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
34e50 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
34e60 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
34e70 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
34e80 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34e90 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  lt_int64(sqlite3
34ea0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
34eb0 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  e3_int64);.SQLIT
34ec0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
34ed0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
34ee0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
34ef0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
34f00 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34f10 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
34f20 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
34f30 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
34f40 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
34f50 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
34f60 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
34f70 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34f80 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
34f90 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
34fa0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
34fb0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
34fc0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
34fd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34fe0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
34ff0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
35000 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
35010 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35020 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
35030 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
35040 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
35050 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
35060 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
35070 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
35080 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
35090 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
350a0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
350b0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
350c0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
350d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
350e0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
350f0 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
35100 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
35110 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  quences.**.** ^T
35120 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
35130 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d  dd, remove, or m
35140 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69  odify a [collati
35150 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  on] associated.*
35160 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
35170 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35180 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
35190 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
351a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
351b0 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  e of the collati
351c0 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  on is a UTF-8 st
351d0 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
351e0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
351f0 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
35200 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
35210 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
35220 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
35230 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
35240 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
35250 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35260 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  n16()..** ^Colla
35270 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20  tion names that 
35280 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63  compare equal ac
35290 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69  cording to [sqli
352a0 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20  te3_strnicmp()] 
352b0 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
352c0 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65  d to be the same
352d0 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   name..**.** ^(T
352e0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
352f0 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73  t (eTextRep) mus
35300 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  t be one of the 
35310 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75  constants:.** <u
35320 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
35330 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69  TE_UTF8],.** <li
35340 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  > [SQLITE_UTF16L
35350 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
35360 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
35370 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
35380 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  F16], or.** <li>
35390 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
353a0 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LIGNED]..** </ul
353b0 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78  >)^.** ^The eTex
353c0 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65  tRep argument de
353d0 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63  termines the enc
353e0 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73  oding of strings
353f0 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68   passed.** to th
35400 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
35410 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78  tion callback, x
35420 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  Callback..** ^Th
35430 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  e [SQLITE_UTF16]
35440 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46   and [SQLITE_UTF
35450 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
35460 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a  es for eTextRep.
35470 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73  ** force strings
35480 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74   to be UTF16 wit
35490 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  h native byte or
354a0 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  der..** ^The [SQ
354b0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
354c0 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54  ED] value for eT
354d0 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74  extRep forces st
354e0 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a  rings to begin.*
354f0 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74  * on an even byt
35500 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a  e address..**.**
35510 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67   ^The fourth arg
35520 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20  ument, pArg, is 
35530 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
35540 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
35550 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68   is passed.** th
35560 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
35570 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
35580 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
35590 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ction callback..
355a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
355b0 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c   argument, xCall
355c0 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74  back, is a point
355d0 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  er to the collat
355e0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ing function..**
355f0 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61   ^Multiple colla
35600 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63  ting functions c
35610 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
35620 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
35630 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68  name but.** with
35640 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
35650 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61  Rep parameters a
35660 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  nd SQLite will u
35670 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20  se whichever.** 
35680 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
35690 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
356a0 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73  nt of data trans
356b0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  formation..** ^I
356c0 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20  f the xCallback 
356d0 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c  argument is NULL
356e0 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   then the collat
356f0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  ing function is.
35700 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68  ** deleted.  ^Wh
35710 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67  en all collating
35720 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e   functions havin
35730 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
35740 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20  are deleted,.** 
35750 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69  that collation i
35760 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62  s no longer usab
35770 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  le..**.** ^The c
35780 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35790 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  n callback is in
357a0 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70  voked with a cop
357b0 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a  y of the pArg .*
357c0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  * application da
357d0 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77  ta pointer and w
357e0 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20  ith two strings 
357f0 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  in the encoding 
35800 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
35810 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  the eTextRep arg
35820 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c  ument.  The coll
35830 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
35840 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a  ust return an.**
35850 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73   integer that is
35860 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c   negative, zero,
35870 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20   or positive.** 
35880 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
35890 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
358a0 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
358b0 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
358c0 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65  second,.** respe
358d0 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c  ctively.  A coll
358e0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
358f0 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72  ust always retur
35900 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65  n the same answe
35910 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73  r.** given the s
35920 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20  ame inputs.  If 
35930 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c  two or more coll
35940 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
35950 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a  are registered.*
35960 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f  * to the same co
35970 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73  llation name (us
35980 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54  ing different eT
35990 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74  extRep values) t
359a0 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20  hen all.** must 
359b0 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65  give an equivale
359c0 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69  nt answer when i
359d0 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69  nvoked with equi
359e0 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a  valent strings..
359f0 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** The collating
35a00 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f   function must o
35a10 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  bey the followin
35a20 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72  g properties for
35a30 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20   all.** strings 
35a40 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a  A, B, and C:.**.
35a50 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
35a60 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d  If A==B then B==
35a70 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  A..** <li> If A=
35a80 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e  =B and B==C then
35a90 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   A==C..** <li> I
35aa0 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26  f A&lt;B THEN B&
35ab0 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  gt;A..** <li> If
35ac0 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74   A&lt;B and B&lt
35ad0 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a  ;C then A&lt;C..
35ae0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ol>.**.** I
35af0 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  f a collating fu
35b00 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79  nction fails any
35b10 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f   of the above co
35b20 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
35b30 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20  at.** collating 
35b40 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67  function is  reg
35b50 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64  istered and used
35b60 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
35b70 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
35b80 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
35b90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35ba0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35bb0 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
35bc0 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
35bd0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
35be0 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69   with the additi
35bf0 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73  on that the xDes
35c00 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
35c10 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67   invoked on pArg
35c20 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c   when.** the col
35c30 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
35c40 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  is deleted..** ^
35c50 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  Collating functi
35c60 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ons are deleted 
35c70 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76  when they are ov
35c80 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
35c90 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68  r.** calls to th
35ca0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
35cb0 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f  tion functions o
35cc0 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64  r when the.** [d
35cd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35ce0 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73  on] is closed us
35cf0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
35d00 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  se()]..**.** ^Th
35d10 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
35d20 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75  ack is <u>not</u
35d30 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20  > called if the 
35d40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
35d50 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
35d60 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  ) function fails
35d70 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
35d80 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  that invoke.** s
35d90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
35da0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74  llation_v2() wit
35db0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65  h a non-NULL xDe
35dc0 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73  stroy argument s
35dd0 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20  hould .** check 
35de0 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
35df0 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74  and dispose of t
35e00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
35e10 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ata pointer.** t
35e20 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72  hemselves rather
35e30 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20   than expecting 
35e40 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77  SQLite to deal w
35e50 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e  ith it for them.
35e60 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66  .** This is diff
35e70 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79  erent from every
35e80 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
35e90 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e  terface.  The in
35ea0 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20  consistency .** 
35eb0 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62  is unfortunate b
35ec0 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  ut cannot be cha
35ed0 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  nged without bre
35ee0 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20  aking backwards 
35ef0 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
35f00 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  y..**.** See als
35f10 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  o:  [sqlite3_col
35f20 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
35f30 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
35f40 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
35f50 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
35f60 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
35f70 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
35f80 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
35f90 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
35fa0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
35fb0 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
35fc0 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
35fd0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
35fe0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
35ff0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51  nst void*).);.SQ
36000 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
36010 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36020 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
36030 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
36040 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
36050 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
36060 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
36070 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
36080 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36090 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
360a0 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
360b0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
360c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
360d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
360e0 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
360f0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
36100 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
36110 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
36120 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
36130 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
36140 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
36150 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
36160 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
36170 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
36180 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
36190 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76  cks.**.** ^To av
361a0 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65  oid having to re
361b0 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61  gister all colla
361c0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62  tion sequences b
361d0 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65  efore a database
361e0 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c  .** can be used,
361f0 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61   a single callba
36200 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  ck function may 
36210 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  be registered wi
36220 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  th the.** [datab
36230 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36240 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
36250 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
36260 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
36270 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
36280 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uired..**.** ^If
36290 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
362a0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
362b0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  g the sqlite3_co
362c0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
362d0 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74   API,.** then it
362e0 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e   is passed the n
362f0 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65  ames of undefine
36300 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
36310 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73  ences as strings
36320 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55  .** encoded in U
36330 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65  TF-8. ^If sqlite
36340 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
36350 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a  ed16() is used,.
36360 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65  ** the names are
36370 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31   passed as UTF-1
36380 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74  6 in machine nat
36390 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
363a0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69  ** ^A call to ei
363b0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65  ther function re
363c0 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74  places the exist
363d0 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65  ing collation-ne
363e0 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  eded callback..*
363f0 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20  *.** ^(When the 
36400 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
36410 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
36420 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
36430 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
36440 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
36450 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
36460 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
36470 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
36480 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
36490 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  6().  The second
364a0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
364b0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
364c0 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68  nection.  The th
364d0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
364e0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  one of [SQLITE_U
364f0 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
36500 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  F16BE],.** or [S
36510 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
36520 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d  indicating the m
36530 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f  ost desirable fo
36540 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  rm of the collat
36550 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
36560 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
36570 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  d.  The fourth p
36580 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
36590 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
365a0 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
365b0 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a  n sequence.)^.**
365c0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
365d0 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
365e0 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65   register the de
365f0 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  sired collation 
36600 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
36610 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36620 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
36630 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36640 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
36650 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36660 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  lation_v2()]..*/
36670 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
36680 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
36690 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
366a0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
366b0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
366c0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
366d0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
366e0 72 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  r*).);.SQLITE_AP
366f0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
36700 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
36710 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
36720 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
36730 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
36740 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
36750 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23  nst void*).);..#
36760 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53  ifdef SQLITE_HAS
36770 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65  _CODEC./*.** Spe
36780 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72  cify the key for
36790 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61   an encrypted da
367a0 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f  tabase.  This ro
367b0 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a  utine should be.
367c0 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20  ** called right 
367d0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70  after sqlite3_op
367e0 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  en()..**.** The 
367f0 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
36800 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
36810 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
36820 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
36830 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
36840 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
36850 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
36860 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
36870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36880 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
36890 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
368a0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
368b0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
368c0 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 53   The key */.);.S
368d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
368e0 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a 20 20  lite3_key_v2(.  
368f0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
36900 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
36910 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
36920 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
36930 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
36940 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  e,           /* 
36950 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  Name of the data
36960 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
36970 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
36980 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
36990 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
369a0 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20   Change the key 
369b0 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  on an open datab
369c0 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72  ase.  If the cur
369d0 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73  rent database is
369e0 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65   not.** encrypte
369f0 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  d, this routine 
36a00 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e  will encrypt it.
36a10 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20    If pNew==0 or 
36a20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20  nNew==0, the.** 
36a30 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72  database is decr
36a40 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ypted..**.** The
36a50 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
36a60 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
36a70 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
36a80 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
36a90 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
36aa0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
36ab0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
36ac0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
36ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36ae0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
36af0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
36b00 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
36b10 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
36b20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
36b30 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
36b40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b   int sqlite3_rek
36b50 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  ey_v2(.  sqlite3
36b60 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
36b70 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
36b80 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
36b90 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  d */.  const cha
36ba0 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20  r *zDbName,     
36bb0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
36bc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f   the database */
36bd0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
36be0 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
36bf0 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79    /* The new key
36c00 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70   */.);../*.** Sp
36c10 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
36c20 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53  tion key for a S
36c30 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  EE database.  Un
36c40 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
36c50 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
36c60 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  SEE routines wil
36c70 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  l work..*/.SQLIT
36c80 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
36c90 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28  e3_activate_see(
36ca0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
36cb0 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
36cc0 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
36cd0 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
36ce0 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  dif..#ifdef SQLI
36cf0 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a  TE_ENABLE_CEROD.
36d00 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
36d10 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
36d20 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74   for a CEROD dat
36d30 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
36d40 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
36d50 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20  ne of the CEROD 
36d60 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
36d70 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  rk..*/.SQLITE_AP
36d80 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  I void sqlite3_a
36d90 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20  ctivate_cerod(. 
36da0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
36db0 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
36dc0 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
36dd0 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
36de0 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
36df0 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
36e00 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
36e10 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20   Time.**.** The 
36e20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
36e30 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
36e40 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
36e50 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78  ad to suspend ex
36e60 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61  ecution.** for a
36e70 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72  t least a number
36e80 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
36e90 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74   specified in it
36ea0 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  s parameter..**.
36eb0 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74  ** If the operat
36ec0 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20  ing system does 
36ed0 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65  not support slee
36ee0 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a  p requests with.
36ef0 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74  ** millisecond t
36f00 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20  ime resolution, 
36f10 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69  then the time wi
36f20 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70  ll be rounded up
36f30 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65   to.** the neare
36f40 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e  st second. The n
36f50 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
36f60 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
36f70 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65  ctually.** reque
36f80 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70  sted from the op
36f90 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
36fa0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
36fb0 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  * ^SQLite implem
36fc0 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
36fd0 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
36fe0 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
36ff0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
37000 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
37010 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74  s] object.  If t
37020 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
37030 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66  od.** of the def
37040 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20  ault VFS is not 
37050 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72  implemented corr
37060 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d  ectly, or not im
37070 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20  plemented at.** 
37080 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65  all, then the be
37090 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
370a0 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65  3_sleep() may de
370b0 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64  viate from the d
370c0 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e  escription.** in
370d0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
370e0 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c  ragraphs..*/.SQL
370f0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
37100 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
37110 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37120 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
37130 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
37140 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a  orary Files.**.*
37150 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62  * ^(If this glob
37160 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
37170 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
37180 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
37190 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
371a0 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
371b0 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
371c0 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
371d0 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
371e0 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e  d by SQLite when
371f0 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
37200 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  n [sqlite3_vfs |
37210 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65   VFS].** will be
37220 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
37230 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49  directory.)^  ^I
37240 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
37250 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
37260 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
37270 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61  e performs a sea
37280 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
37290 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  priate.** tempor
372a0 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f  ary file directo
372b0 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
372c0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
372d0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
372e0 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65  variable in more
372f0 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72   than one.** thr
37300 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20  ead at a time.  
37310 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
37320 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
37330 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
37340 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65  * if a [database
37350 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
37360 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68  being used at th
37370 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61  e same time in a
37380 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72   separate.** thr
37390 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e  ead..** It is in
373a0 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
373b0 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
373c0 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
373d0 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
373e0 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
373f0 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
37400 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
37410 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
37420 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74   called and that
37430 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72   this variable r
37440 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a  emain unchanged.
37450 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ** thereafter..*
37460 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f  *.** ^The [temp_
37470 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37480 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
37490 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
374a0 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
374b0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
374c0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
374d0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
374e0 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72  c].  ^Furthermor
374f0 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f  e,.** the [temp_
37500 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37510 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61  pragma] always a
37520 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20  ssumes that any 
37530 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74  string.** that t
37540 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69  his variable poi
37550 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69  nts to is held i
37560 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
37570 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
37580 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20  te3_malloc] and 
37590 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61  the pragma may a
375a0 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
375b0 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73  hat memory.** us
375c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
375d0 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66  e]..** Hence, if
375e0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
375f0 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63  s modified direc
37600 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73  tly, either it s
37610 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65  hould be.** made
37620 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f   NULL or made to
37630 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
37640 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
37650 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a  sqlite3_malloc].
37660 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75  ** or else the u
37670 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f  se of the [temp_
37680 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37690 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62  pragma] should b
376a0 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a  e avoided..**.**
376b0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
376c0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
376d0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
376e0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
376f0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
37700 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
37710 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f  [sqlite3_open] o
37720 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
37730 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  v2].  Otherwise,
37740 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
37750 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
37760 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
37770 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
37780 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73 20   fail.  Here is 
37790 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66  an.** example of
377a0 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73 20   how to do this 
377b0 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20 74  using C++ with t
377c0 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  he Windows Runti
377d0 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  me:.**.** <block
377e0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c  quote><pre>.** L
377f0 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20 57  PCWSTR zPath = W
37800 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a  indows::Storage:
37810 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74 61  :ApplicationData
37820 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26  ::Current->.** &
37830 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f 72  nbsp;     Tempor
37840 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68 2d  aryFolder->Path-
37850 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61 72  >Data();.** char
37860 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d 41   zPathBuf&#91;MA
37870 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b 3b  X_PATH + 1&#93;;
37880 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74 68  .** memset(zPath
37890 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28 7a  Buf, 0, sizeof(z
378a0 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57 69  PathBuf));.** Wi
378b0 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79 74  deCharToMultiByt
378c0 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a 50  e(CP_UTF8, 0, zP
378d0 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42 75  ath, -1, zPathBu
378e0 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42  f, sizeof(zPathB
378f0 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  uf),.** &nbsp;  
37900 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a     NULL, NULL);.
37910 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  ** sqlite3_temp_
37920 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c 69  directory = sqli
37930 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73 22  te3_mprintf("%s"
37940 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20  , zPathBuf);.** 
37950 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
37960 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te>.*/.SQLITE_AP
37970 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  I SQLITE_EXTERN 
37980 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
37990 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
379a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
379b0 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
379c0 72 20 48 6f 6c 64 69 6e 67 20 44 61 74 61 62 61  r Holding Databa
379d0 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e  se Files.**.** ^
379e0 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20  (If this global 
379f0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
37a00 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
37a10 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
37a20 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
37a30 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
37a40 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
37a50 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c  all database fil
37a60 65 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  es.** specified 
37a70 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20  with a relative 
37a80 70 61 74 68 6e 61 6d 65 20 61 6e 64 20 63 72 65  pathname and cre
37a90 61 74 65 64 20 6f 72 20 61 63 63 65 73 73 65 64  ated or accessed
37aa0 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77 68   by.** SQLite wh
37ab0 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74  en using a built
37ac0 2d 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71 6c  -in windows [sql
37ad0 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 20  ite3_vfs | VFS] 
37ae0 77 69 6c 6c 20 62 65 20 61 73 73 75 6d 65 64 0a  will be assumed.
37af0 2a 2a 20 74 6f 20 62 65 20 72 65 6c 61 74 69 76  ** to be relativ
37b00 65 20 74 6f 20 74 68 61 74 20 64 69 72 65 63 74  e to that direct
37b10 6f 72 79 2e 29 5e 20 5e 49 66 20 74 68 69 73 20  ory.)^ ^If this 
37b20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
37b30 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 74  LL.** pointer, t
37b40 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
37b50 65 73 20 74 68 61 74 20 61 6c 6c 20 64 61 74 61  es that all data
37b60 62 61 73 65 20 66 69 6c 65 73 20 73 70 65 63 69  base files speci
37b70 66 69 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 72  fied.** with a r
37b80 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65  elative pathname
37b90 20 61 72 65 20 72 65 6c 61 74 69 76 65 20 74 6f   are relative to
37ba0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
37bb0 65 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74 68  ectory.** for th
37bc0 65 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c 79  e process.  Only
37bd0 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
37be0 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 20 74 68   makes use of th
37bf0 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72  is global.** var
37c00 69 61 62 6c 65 3b 20 69 74 20 69 73 20 69 67 6e  iable; it is ign
37c10 6f 72 65 64 20 62 79 20 74 68 65 20 75 6e 69 78  ored by the unix
37c20 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e   VFS..**.** Chan
37c30 67 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 6f  ging the value o
37c40 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
37c50 77 68 69 6c 65 20 61 20 64 61 74 61 62 61 73 65  while a database
37c60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a 2a   connection is.*
37c70 2a 20 6f 70 65 6e 20 63 61 6e 20 72 65 73 75 6c  * open can resul
37c80 74 20 69 6e 20 61 20 63 6f 72 72 75 70 74 20 64  t in a corrupt d
37c90 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49  atabase..**.** I
37ca0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
37cb0 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
37cc0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
37cd0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
37ce0 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
37cf0 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
37d00 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
37d10 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
37d20 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
37d30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37d40 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
37d50 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
37d60 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
37d70 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
37d80 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
37d90 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
37da0 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
37db0 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
37dc0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
37dd0 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
37de0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
37df0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
37e00 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
37e10 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
37e20 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
37e30 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
37e40 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
37e50 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
37e60 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
37e70 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
37e80 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
37e90 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
37ea0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
37eb0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
37ec0 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
37ed0 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
37ee0 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
37ef0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
37f00 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
37f10 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
37f20 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
37f30 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
37f40 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
37f50 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
37f60 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
37f70 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
37f80 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
37f90 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
37fa0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
37fb0 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
37fc0 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
37fd0 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
37fe0 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
37ff0 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
38000 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
38010 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
38020 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
38030 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
38040 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
38050 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
38060 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
38070 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
38080 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
38090 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  */.SQLITE_API SQ
380a0 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
380b0 20 2a 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 64   *sqlite3_data_d
380c0 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
380d0 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
380e0 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20  For Auto-Commit 
380f0 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  Mode.** KEYWORDS
38100 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  : {autocommit mo
38110 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  de}.**.** ^The s
38120 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
38130 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  ommit() interfac
38140 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  e returns non-ze
38150 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66  ro or.** zero if
38160 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62   the given datab
38170 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
38180 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61  s or is not in a
38190 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a  utocommit mode,.
381a0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
381b0 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f    ^Autocommit mo
381c0 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61  de is on by defa
381d0 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d  ult..** ^Autocom
381e0 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61  mit mode is disa
381f0 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e  bled by a [BEGIN
38200 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
38210 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
38220 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62   is re-enabled b
38230 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20  y a [COMMIT] or 
38240 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a  [ROLLBACK]..**.*
38250 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e  * If certain kin
38260 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63  ds of errors occ
38270 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e  ur on a statemen
38280 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69  t within a multi
38290 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72  -statement.** tr
382a0 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72  ansaction (error
382b0 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c  s including [SQL
382c0 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_FULL], [SQLI
382d0 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53  TE_IOERR],.** [S
382e0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53  QLITE_NOMEM], [S
382f0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64  QLITE_BUSY], and
38300 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
38310 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a  PT]) then the.**
38320 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67   transaction mig
38330 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ht be rolled bac
38340 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
38350 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74    The only way t
38360 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68  o.** find out wh
38370 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74  ether SQLite aut
38380 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
38390 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  d back the trans
383a0 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20  action after.** 
383b0 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75  an error is to u
383c0 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  se this function
383d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
383e0 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65  er thread change
383f0 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74  s the autocommit
38400 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64   status of the d
38410 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
38420 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73  ction while this
38430 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e   routine is runn
38440 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
38450 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73  turn value.** is
38460 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53   undefined..*/.S
38470 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
38480 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
38490 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
384a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
384b0 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61   Find The Databa
384c0 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50  se Handle Of A P
384d0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
384e0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
384f0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
38500 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
38510 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
38520 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
38530 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20  e.** to which a 
38540 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
38550 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e  ent] belongs.  ^
38560 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
38570 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74  nnection].** ret
38580 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
38590 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68  _db_handle is th
385a0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
385b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
385c0 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72  that was the fir
385d0 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  st argument.** t
385e0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  o the [sqlite3_p
385f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c  repare_v2()] cal
38600 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e  l (or its varian
38610 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65  ts) that was use
38620 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74  d to.** create t
38630 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  he statement in 
38640 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
38650 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  .*/.SQLITE_API s
38660 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
38670 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
38680 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
38690 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 72   CAPI3REF: Retur
386a0 6e 20 54 68 65 20 46 69 6c 65 6e 61 6d 65 20 46  n The Filename F
386b0 6f 72 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  or A Database Co
386c0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
386d0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 66  The sqlite3_db_f
386e0 69 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74  ilename(D,N) int
386f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
38700 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 69   pointer to a fi
38710 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69  lename.** associ
38720 61 74 65 64 20 77 69 74 68 20 64 61 74 61 62 61  ated with databa
38730 73 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69  se N of connecti
38740 6f 6e 20 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e  on D.  ^The main
38750 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a   database file.*
38760 2a 20 68 61 73 20 74 68 65 20 6e 61 6d 65 20 22  * has the name "
38770 6d 61 69 6e 22 2e 20 20 49 66 20 74 68 65 72 65  main".  If there
38780 20 69 73 20 6e 6f 20 61 74 74 61 63 68 65 64 20   is no attached 
38790 64 61 74 61 62 61 73 65 20 4e 20 6f 6e 20 74 68  database N on