System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 86ccd18d1bb6d9b10ccfadb2d6ae17363e123a9b:


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 34 22 0a 23 64 65 66 69 6e 65 20 53 51  .8.4".#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 34 0a 23 64 65 66  BER 3008004.#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 34 2d  E_ID      "2014-
1070: 30 33 2d 31 30 20 31 32 3a 32 30 3a 33 37 20 35  03-10 12:20:37 5
1080: 33 30 61 31 65 65 37 64 63 32 34 33 35 66 38 30  30a1ee7dc2435f80
1090: 39 36 30 63 65 34 37 31 30 61 33 63 32 64 32 62  960ce4710a3c2d2b
10a0: 66 61 61 63 63 63 35 22 0a 0a 2f 2a 0a 2a 2a 20  faaccc5"../*.** 
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 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
3f50: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
3f60: 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
3f70: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
3f80: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3f90: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3fa0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3fb0: 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ning..** <li> Th
3fc0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
3fd0: 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  st not modify th
3fe0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
3ff0: 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f  text passed into
4000: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64  .**      the 2nd
4010: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
4020: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
4030: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
4040: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
4050: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ul>.*/.SQLITE
4060: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
4070: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
4080: 2a 2c 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: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
40b0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
40c0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40e0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
40f0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
4100: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
4110: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
4120: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
4130: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
4140: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  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: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
4180: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
4190: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
41a0: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
41b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41c0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
41d0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
41e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
41f0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4200: 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
4210: 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65  E_OK {error code
4220: 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a  } {error codes}.
4230: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65  ** KEYWORDS: {re
4240: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75  sult code} {resu
4250: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
4260: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63  Many SQLite func
4270: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20  tions return an 
4280: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63  integer result c
4290: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74  ode from the set
42a0: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69   shown.** here i
42b0: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63  n order to indic
42c0: 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66  ate success or f
42d0: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
42e0: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
42f0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
4300: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
4310: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
4320: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
4330: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
4340: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4350: 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  des],.** [sqlite
4360: 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
4370: 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f  ct()] [SQLITE_RO
4380: 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74 20  LLBACK | result 
4390: 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69  codes]..*/.#defi
43a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20  ne SQLITE_OK    
43b0: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75         0   /* Su
43c0: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20  ccessful result 
43d0: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d  */./* beginning-
43e0: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
43f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4400: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20  _ERROR        1 
4410: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
4420: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
4430: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
4440: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20  LITE_INTERNAL   
4450: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61    2   /* Interna
4460: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  l logic error in
4470: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69   SQLite */.#defi
4480: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20  ne SQLITE_PERM  
4490: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63         3   /* Ac
44a0: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20  cess permission 
44b0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
44c0: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20  e SQLITE_ABORT  
44d0: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c        4   /* Cal
44e0: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
44f0: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74  quested an abort
4500: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4510: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20  TE_BUSY         
4520: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  5   /* The datab
4530: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  ase file is lock
4540: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4550: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20  LITE_LOCKED     
4560: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65    6   /* A table
4570: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
4580: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
4590: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d  efine SQLITE_NOM
45a0: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  EM        7   /*
45b0: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c   A malloc() fail
45c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
45d0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20  LITE_READONLY   
45e0: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74    8   /* Attempt
45f0: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64   to write a read
4600: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f  only database */
4610: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4620: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20  INTERRUPT    9  
4630: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65   /* Operation te
4640: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69  rminated by sqli
4650: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a  te3_interrupt()*
4660: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4670: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20  _IOERR       10 
4680: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f    /* Some kind o
4690: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  f disk I/O error
46a0: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65   occurred */.#de
46b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
46c0: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20  UPT     11   /* 
46d0: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73  The database dis
46e0: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f  k image is malfo
46f0: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rmed */.#define 
4700: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
4710: 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f     12   /* Unkno
4720: 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c  wn opcode in sql
4730: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
4740: 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  l() */.#define S
4750: 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20  QLITE_FULL      
4760: 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74    13   /* Insert
4770: 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75  ion failed becau
4780: 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66  se database is f
4790: 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ull */.#define S
47a0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20  QLITE_CANTOPEN  
47b0: 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65    14   /* Unable
47c0: 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
47d0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
47e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f  efine SQLITE_PRO
47f0: 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a  TOCOL    15   /*
4800: 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70   Database lock p
4810: 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f  rotocol error */
4820: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4830: 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20  EMPTY       16  
4840: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20   /* Database is 
4850: 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65  empty */.#define
4860: 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20   SQLITE_SCHEMA  
4870: 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20      17   /* The 
4880: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
4890: 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69  changed */.#defi
48a0: 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47  ne SQLITE_TOOBIG
48b0: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74        18   /* St
48c0: 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63  ring or BLOB exc
48d0: 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20  eeds size limit 
48e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
48f0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39  E_CONSTRAINT  19
4900: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20     /* Abort due 
4910: 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69  to constraint vi
4920: 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69  olation */.#defi
4930: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54  ne SQLITE_MISMAT
4940: 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61  CH    20   /* Da
4950: 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68  ta type mismatch
4960: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4970: 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32  TE_MISUSE      2
4980: 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75  1   /* Library u
4990: 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  sed incorrectly 
49a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
49b0: 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32  E_NOLFS       22
49c0: 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65     /* Uses OS fe
49d0: 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f  atures not suppo
49e0: 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a  rted on host */.
49f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
4a00: 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20  UTH        23   
4a10: 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  /* Authorization
4a20: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
4a30: 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54  ne SQLITE_FORMAT
4a40: 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75        24   /* Au
4a50: 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65  xiliary database
4a60: 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f   format error */
4a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a80: 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20  RANGE       25  
4a90: 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65   /* 2nd paramete
4aa0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
4ab0: 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a  d out of range *
4ac0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4ad0: 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20  _NOTADB      26 
4ae0: 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64    /* File opened
4af0: 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64   that is not a d
4b00: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4b10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4b20: 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20 20  OTICE      27   
4b30: 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73  /* Notifications
4b40: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4b50: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4b60: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20  QLITE_WARNING   
4b70: 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e    28   /* Warnin
4b80: 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  gs from sqlite3_
4b90: 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  log() */.#define
4ba0: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20   SQLITE_ROW     
4bb0: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69      100  /* sqli
4bc0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61  te3_step() has a
4bd0: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79  nother row ready
4be0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4bf0: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31  TE_DONE        1
4c00: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  01  /* sqlite3_s
4c10: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68  tep() has finish
4c20: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a  ed executing */.
4c30: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d  /* end-of-error-
4c40: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  codes */../*.** 
4c50: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64  CAPI3REF: Extend
4c60: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
4c70: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78  ** KEYWORDS: {ex
4c80: 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
4c90: 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72  e} {extended err
4ca0: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4cb0: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
4cc0: 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65   result code} {e
4cd0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4ce0: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69  odes}.**.** In i
4cf0: 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  ts default confi
4d00: 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65  guration, SQLite
4d10: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65   API routines re
4d20: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69  turn one of 26 i
4d30: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
4d40: 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
4d50: 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20  des].  However, 
4d60: 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73  experience has s
4d70: 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f  hown that many o
4d80: 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c  f.** these resul
4d90: 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20  t codes are too 
4da0: 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20  coarse-grained. 
4db0: 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f   They do not pro
4dc0: 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20  vide as.** much 
4dd0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
4de0: 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72  t problems as pr
4df0: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20  ogrammers might 
4e00: 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66  like.  In an eff
4e10: 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73  ort to.** addres
4e20: 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65  s this, newer ve
4e30: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
4e40: 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20   (version 3.3.8 
4e50: 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75  and later) inclu
4e60: 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f  de.** support fo
4e70: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73  r additional res
4e80: 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70  ult codes that p
4e90: 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61  rovide more deta
4ea0: 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  iled information
4eb0: 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73  .** about errors
4ec0: 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72  . The extended r
4ed0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4ee0: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
4ef0: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20  led.** on a per 
4f00: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4f10: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20  ion basis using 
4f20: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4f30: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
4f40: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a  codes()] API..**
4f50: 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20  .** Some of the 
4f60: 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64  available extend
4f70: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4f80: 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e  are listed here.
4f90: 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65  .** One may expe
4fa0: 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ct the number of
4fb0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4fc0: 20 63 6f 64 65 73 20 77 69 6c 6c 20 69 6e 63 72   codes will incr
4fd0: 65 61 73 65 0a 2a 2a 20 6f 76 65 72 20 74 69 6d  ease.** over tim
4fe0: 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  e.  Software tha
4ff0: 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20  t uses extended 
5000: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f  result codes sho
5010: 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f  uld expect.** to
5020: 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20   see new result 
5030: 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20  codes in future 
5040: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
5050: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  te..**.** The SQ
5060: 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63  LITE_OK result c
5070: 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62  ode will never b
5080: 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20  e extended.  It 
5090: 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62  will always.** b
50a0: 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a  e exactly zero..
50b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
50c0: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20  E_IOERR_READ    
50d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29  E_IOERR | (1<<8)
50f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5100: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
5110: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
5120: 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29  _IOERR | (2<<8))
5130: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5140: 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20  IOERR_WRITE     
5150: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5160: 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a  IOERR | (3<<8)).
5170: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5180: 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20  OERR_FSYNC      
5190: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
51a0: 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OERR | (4<<8)).#
51b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51c0: 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20  ERR_DIR_FSYNC   
51d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51e0: 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64  ERR | (5<<8)).#d
51f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5200: 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20  RR_TRUNCATE     
5210: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5220: 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  RR | (6<<8)).#de
5230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5240: 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20  R_FSTAT         
5250: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5260: 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66  R | (7<<8)).#def
5270: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5280: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _UNLOCK         
5290: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52a0: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
52c0: 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  RDLOCK          
52d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52e0: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
52f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
5300: 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
5310: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5320: 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (10<<8)).#defin
5330: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42  e SQLITE_IOERR_B
5340: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20  LOCKED          
5350: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5360: 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (11<<8)).#defin
5370: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e  e SQLITE_IOERR_N
5380: 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20  OMEM            
5390: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
53a0: 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (12<<8)).#defin
53b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41  e SQLITE_IOERR_A
53c0: 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20  CCESS           
53d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
53e0: 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (13<<8)).#defin
53f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
5400: 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b  HECKRESERVEDLOCK
5410: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5420: 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (14<<8)).#defin
5430: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c  e SQLITE_IOERR_L
5440: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  OCK             
5450: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5460: 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (15<<8)).#defin
5470: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
5480: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20  LOSE            
5490: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
54a0: 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (16<<8)).#defin
54b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
54c0: 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  IR_CLOSE        
54d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
54e0: 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (17<<8)).#defin
54f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
5500: 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20  HMOPEN          
5510: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5520: 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (18<<8)).#defin
5530: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
5540: 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  HMSIZE          
5550: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5560: 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (19<<8)).#defin
5570: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
5580: 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  HMLOCK          
5590: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
55a0: 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (20<<8)).#defin
55b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
55c0: 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  HMMAP           
55d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
55e0: 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (21<<8)).#defin
55f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
5600: 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  EEK             
5610: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5620: 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (22<<8)).#defin
5630: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
5640: 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20  ELETE_NOENT     
5650: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5660: 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (23<<8)).#defin
5670: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d  e SQLITE_IOERR_M
5680: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 20  MAP             
5690: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
56a0: 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (24<<8)).#defin
56b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47  e SQLITE_IOERR_G
56c0: 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20 20  ETTEMPPATH      
56d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
56e0: 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (25<<8)).#defin
56f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
5700: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20 20  ONVPATH         
5710: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5720: 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (26<<8)).#defin
5730: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f  e SQLITE_LOCKED_
5740: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
5750: 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20   (SQLITE_LOCKED 
5760: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5770: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52  ne SQLITE_BUSY_R
5780: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20  ECOVERY         
5790: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20    (SQLITE_BUSY  
57a0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
57b0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
57c0: 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20  SNAPSHOT        
57d0: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
57e0: 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65    |  (2<<8)).#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5800: 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20  OPEN_NOTEMPDIR  
5810: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
5820: 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23  OPEN | (1<<8)).#
5830: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5840: 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20  NTOPEN_ISDIR    
5850: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5860: 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29  NTOPEN | (2<<8))
5870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5880: 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54  CANTOPEN_FULLPAT
5890: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
58a0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38  CANTOPEN | (3<<8
58b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
58c0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50  E_CANTOPEN_CONVP
58d0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
58e0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c  E_CANTOPEN | (4<
58f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5900: 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42  ITE_CORRUPT_VTAB
5910: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5920: 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31  ITE_CORRUPT | (1
5930: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5940: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45  LITE_READONLY_RE
5950: 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51  COVERY       (SQ
5960: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5970: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5980: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5990: 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28  CANTLOCK       (
59a0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
59b0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
59c0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
59d0: 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  Y_ROLLBACK      
59e0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
59f0: 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  Y | (3<<8)).#def
5a00: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5a10: 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20  NLY_DBMOVED     
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5a30: 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  NLY | (4<<8)).#d
5a40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
5a50: 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  RT_ROLLBACK     
5a60: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f       (SQLITE_ABO
5a70: 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RT | (2<<8)).#de
5a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5a90: 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20  TRAINT_CHECK    
5aa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5ab0: 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29  TRAINT | (1<<8))
5ac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ad0: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49  CONSTRAINT_COMMI
5ae0: 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f  THOOK   (SQLITE_
5af0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c  CONSTRAINT | (2<
5b00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b10: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5b20: 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c  OREIGNKEY   (SQL
5b30: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5b40: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
5b50: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5b60: 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  NT_FUNCTION     
5b70: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5b80: 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  NT | (4<<8)).#de
5b90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5ba0: 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20  TRAINT_NOTNULL  
5bb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5bc0: 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29  TRAINT | (5<<8))
5bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5be0: 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41  CONSTRAINT_PRIMA
5bf0: 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  RYKEY   (SQLITE_
5c00: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c  CONSTRAINT | (6<
5c10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5c20: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54  ITE_CONSTRAINT_T
5c30: 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c  RIGGER      (SQL
5c40: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5c50: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
5c60: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5c70: 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20  NT_UNIQUE       
5c80: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5c90: 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  NT | (8<<8)).#de
5ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5cb0: 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20  TRAINT_VTAB     
5cc0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5cd0: 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29  TRAINT | (9<<8))
5ce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5cf0: 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44  CONSTRAINT_ROWID
5d00: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5d10: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c  CONSTRAINT |(10<
5d20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5d30: 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56  ITE_NOTICE_RECOV
5d40: 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c  ER_WAL      (SQL
5d50: 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c  ITE_NOTICE | (1<
5d60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5d70: 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56  ITE_NOTICE_RECOV
5d80: 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c  ER_ROLLBACK (SQL
5d90: 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c  ITE_NOTICE | (2<
5da0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5db0: 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f  ITE_WARNING_AUTO
5dc0: 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c  INDEX       (SQL
5dd0: 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31  ITE_WARNING | (1
5de0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
5df0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
5e00: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
5e10: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
5e20: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
5e30: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5e40: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
5e50: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5e60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
5e70: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
5e80: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
5e90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5ea0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
5eb0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
5ec0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ed0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
5ee0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
5ef0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5f00: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5f10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f20: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5f30: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5f40: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5f50: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f70: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5f80: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5f90: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5fa0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fc0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
5fd0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
5fe0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6000: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
6010: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
6020: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6040: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
6050: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
6060: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6070: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6080: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
6090: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
60a0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
60b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
60c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60d0: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
60e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
60f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6100: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6110: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6120: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
6130: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
6140: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6160: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
6170: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6180: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
61a0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
61b0: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
61c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
61d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
61e0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
61f0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
6200: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6210: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6220: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
6230: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
6240: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6250: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6260: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
6270: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
6280: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6290: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
62a0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
62b0: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
62c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
62d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
62e0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
62f0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
6300: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6310: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6320: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6330: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
6340: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
6350: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6360: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6370: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6380: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
6390: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
63a0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
63b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
63c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
63d0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
63e0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
63f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6400: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6420: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
6430: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
6440: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6450: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
6460: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6470: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
6480: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
6490: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
64a0: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
64b0: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
64c0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
64d0: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
64e0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
64f0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
6500: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
6510: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
6520: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
6530: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
6540: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
6550: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
6560: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
6570: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
6580: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
6590: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
65a0: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
65b0: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
65c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
65d0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
65e0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
65f0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
6600: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6610: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6620: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
6630: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
6640: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
6650: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
6660: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
6670: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
6680: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
6690: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
66a0: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
66b0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
66c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
66d0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
66e0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
66f0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
6700: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
6710: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
6720: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
6730: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
6740: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
6750: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
6760: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
6770: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
6780: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6790: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
67a0: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
67b0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
67c0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
67d0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
67e0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
67f0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6800: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
6810: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
6820: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
6830: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
6840: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
6850: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
6860: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
6870: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
6880: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
6890: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
68a0: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
68b0: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
68c0: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
68d0: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
68e0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
68f0: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
6900: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
6910: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49  anged.  The SQLI
6920: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
6930: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a  ABLE_WHEN_OPEN.*
6940: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20  * flag indicate 
6950: 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e  that a file cann
6960: 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68  ot be deleted wh
6970: 65 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 23 64 65 66  en open..*/.#def
6980: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6990: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
69a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
69b0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
69c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
69d0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
69e0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
69f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6a00: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
6a10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6a20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6a40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a50: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6a60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a70: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6a80: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6a90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6aa0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6ab0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6ac0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6ad0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6ae0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6af0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b10: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6b20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6b30: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6b40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6b50: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6b60: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6b70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b80: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6b90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6ba0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6bb0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6bc0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6bd0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6be0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6bf0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6c00: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6c10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c20: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6c30: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6c40: 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  001000../*.** CA
6c50: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6c60: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
6c70: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
6c80: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
6c90: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6ca0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
6cb0: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
6cc0: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
6cd0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
6ce0: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
6cf0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
6d00: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
6d10: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6d20: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
6d30: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
6d40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6d50: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6d60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6d70: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
6d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6d90: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
6da0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
6db0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6dc0: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
6dd0: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
6de0: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
6df0: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
6e00: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
6e10: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
6e20: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
6e30: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6e40: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
6e50: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6e60: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6e70: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6e80: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
6e90: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
6ea0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6eb0: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
6ec0: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
6ed0: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
6ee0: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
6ef0: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
6f00: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
6f10: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
6f20: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
6f30: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
6f40: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6f50: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
6f60: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6f70: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
6f80: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
6f90: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
6fa0: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
6fb0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
6fc0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6fd0: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
6fe0: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
6ff0: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7000: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
7010: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
7020: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
7030: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
7040: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
7050: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
7060: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
7070: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
7080: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
7090: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
70a0: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
70b0: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
70c0: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
70d0: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
70e0: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
70f0: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
7100: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
7110: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
7120: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
7130: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
7140: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7150: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
7160: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
7170: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
7180: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
7190: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
71a0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
71b0: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
71c0: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
71d0: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
71e0: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
71f0: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
7200: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
7210: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
7220: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
7230: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
7240: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
7250: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
7260: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
7270: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
7280: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
7290: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
72a0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
72b0: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
72c0: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
72d0: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
72e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
72f0: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
7300: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
7310: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
7320: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
7330: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
7340: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
7350: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
7360: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
7370: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
7380: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
7390: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
73a0: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
73b0: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
73c0: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
73d0: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
73e0: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
73f0: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
7400: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
7410: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
7420: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
7430: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
7440: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
7450: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
7460: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
7470: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
7480: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
7490: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
74a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
74b0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
74c0: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
74d0: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
74e0: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
74f0: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
7500: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
7510: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7520: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
7530: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
7540: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
7550: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7560: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
7570: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
7580: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
7590: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
75a0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
75b0: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
75c0: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
75d0: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
75e0: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
75f0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7600: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
7610: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
7620: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7630: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
7640: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
7650: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
7660: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7670: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
7680: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
7690: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
76a0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
76b0: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
76c0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
76d0: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
76e0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
76f0: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
7700: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
7710: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7720: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7730: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
7740: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7750: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
7760: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7770: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
7780: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
7790: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
77a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
77b0: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
77c0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
77d0: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
77e0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
77f0: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
7800: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
7810: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
7820: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
7830: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
7840: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
7850: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
7860: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
7870: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
7880: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
7890: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
78a0: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
78b0: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
78c0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
78d0: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
78e0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
78f0: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
7900: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7910: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
7920: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
7930: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
7940: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
7950: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
7960: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
7970: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
7980: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
7990: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
79a0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
79b0: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
79c0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
79d0: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
79e0: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
79f0: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
7a00: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
7a10: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7a20: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7a30: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
7a40: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7a50: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
7a60: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7a70: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7a80: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7a90: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7aa0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
7ab0: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
7ac0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
7ad0: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
7ae0: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
7af0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
7b00: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
7b10: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
7b20: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
7b30: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
7b40: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
7b50: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
7b60: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
7b70: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
7b80: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
7b90: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
7ba0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
7bb0: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
7bc0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
7bd0: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
7be0: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
7bf0: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
7c00: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
7c10: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
7c20: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
7c30: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
7c40: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
7c50: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
7c60: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
7c70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
7c80: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
7c90: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
7ca0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
7cb0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
7cc0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
7cd0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
7ce0: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
7cf0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
7d00: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
7d10: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
7d20: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
7d30: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
7d40: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
7d50: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
7d60: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
7d70: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
7d80: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
7d90: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
7da0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
7db0: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
7dc0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
7dd0: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
7de0: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
7df0: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
7e00: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
7e10: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
7e20: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
7e30: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
7e40: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
7e50: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7e60: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7e70: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
7e80: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
7e90: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
7ea0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
7eb0: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
7ec0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
7ed0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
7ee0: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
7ef0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
7f00: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
7f10: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
7f20: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
7f30: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
7f40: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7f50: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
7f60: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
7f70: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
7f80: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
7f90: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7fa0: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
7fb0: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
7fc0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
7fd0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
7fe0: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
7ff0: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
8000: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
8010: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
8020: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
8030: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
8040: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
8050: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
8060: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
8070: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
8080: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
8090: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
80a0: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
80b0: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
80c0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
80d0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
80e0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
80f0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
8100: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
8110: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
8120: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
8130: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
8140: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
8150: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8160: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
8170: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
8180: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
8190: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
81a0: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
81b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
81c0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
81d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
81e0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
81f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8200: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
8210: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8220: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
8230: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8240: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
8250: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8260: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
8270: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8280: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
8290: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
82a0: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
82b0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
82c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
82d0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
82e0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
82f0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
8300: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
8310: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
8320: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
8330: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
8340: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
8350: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
8360: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
8370: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
8380: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
8390: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
83a0: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
83b0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
83c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
83d0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
83e0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
83f0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
8400: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
8410: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
8420: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
8430: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
8440: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
8450: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
8460: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
8470: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
8480: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
8490: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
84a0: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
84b0: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
84c0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
84d0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
84e0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
84f0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
8500: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
8510: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
8520: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
8530: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
8540: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
8550: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
8560: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
8570: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
8580: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
8590: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
85a0: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
85b0: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
85c0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
85d0: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
85e0: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
85f0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
8600: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
8610: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
8620: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
8630: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8640: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
8650: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
8660: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
8670: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
8680: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8690: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
86a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
86b0: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
86c0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
86d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
86e0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
86f0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
8700: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8710: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8720: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
8730: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8740: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
8750: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
8760: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
8770: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
8780: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
8790: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
87a0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
87b0: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
87c0: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
87d0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
87e0: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
87f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8800: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
8810: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
8820: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8830: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
8840: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
8850: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
8860: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
8870: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
8880: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
8890: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
88a0: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
88b0: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
88c0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
88d0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
88e0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
88f0: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
8900: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
8910: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
8920: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
8930: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
8940: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8950: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8960: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
8970: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
8980: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
8990: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
89a0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
89b0: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
89c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
89d0: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
89e0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
89f0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8a00: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74  rsion 2 */.  int
8a10: 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74   (*xFetch)(sqlit
8a20: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8a30: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69  3_int64 iOfst, i
8a40: 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a  nt iAmt, void **
8a50: 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  pp);.  int (*xUn
8a60: 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  fetch)(sqlite3_f
8a70: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8a80: 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20  t64 iOfst, void 
8a90: 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  *p);.  /* Method
8aa0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
8ab0: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  d for version 3 
8ac0: 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  */.  /* Addition
8ad0: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
8ae0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
8af0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
8b00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
8b10: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
8b20: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a  Control Opcodes.
8b30: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
8b40: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
8b50: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
8b60: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
8b70: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
8b80: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
8b90: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
8ba0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
8bb0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8bc0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
8bd0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
8be0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8bf0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8c00: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
8c10: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
8c20: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
8c30: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
8c40: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
8c50: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
8c60: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
8c70: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
8c80: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
8c90: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
8ca0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8cb0: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
8cc0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
8cd0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8ce0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
8cf0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
8d00: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
8d10: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
8d20: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
8d30: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
8d40: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79  testing and only
8d50: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
8d60: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
8d70: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65  TE_TEST.** is de
8d80: 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a  fined..** <ul>.*
8d90: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8da0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8db0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8dc0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8dd0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8de0: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8df0: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8e00: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8e10: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8e20: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8e30: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8e40: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8e50: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8e60: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8e70: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8e80: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8e90: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8ea0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8eb0: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8ec0: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8ed0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8ee0: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8ef0: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8f00: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8f10: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8f20: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8f30: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8f40: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8f50: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
8f60: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8f70: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8f80: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8f90: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
8fa0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
8fb0: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
8fc0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8fd0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
8fe0: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
8ff0: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
9000: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
9010: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
9020: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
9030: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
9040: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
9050: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
9060: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
9070: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
9080: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
9090: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
90a0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
90b0: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
90c0: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
90d0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
90e0: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
90f0: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
9100: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
9110: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
9120: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9130: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
9140: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9150: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
9160: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9170: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
9180: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9190: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
91a0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
91b0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
91c0: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
91d0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
91e0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
91f0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
9200: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9210: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
9220: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
9230: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
9240: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
9250: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9260: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
9270: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
9280: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
9290: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
92a0: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
92b0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
92c0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
92d0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
92e0: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
92f0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
9300: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
9310: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
9320: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
9330: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
9340: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
9350: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
9360: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
9370: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
9380: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
9390: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
93a0: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
93b0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
93c0: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
93d0: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
93e0: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
93f0: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
9400: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
9410: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
9420: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
9430: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
9440: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
9450: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
9460: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
9470: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
9480: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
9490: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
94a0: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
94b0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
94c0: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
94d0: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
94e0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
94f0: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
9500: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
9510: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
9520: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
9530: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
9540: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
9550: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
9560: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
9570: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
9580: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9590: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
95a0: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
95b0: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
95c0: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
95d0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
95e0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
95f0: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
9600: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
9610: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
9620: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
9630: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9640: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
9650: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
9660: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9670: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
9680: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
9690: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
96a0: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
96b0: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
96c0: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
96d0: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
96e0: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
96f0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
9700: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9710: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
9720: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
9730: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
9740: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
9750: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
9760: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9770: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9780: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9790: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
97a0: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
97b0: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
97c0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
97d0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
97e0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
97f0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9800: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
9810: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9820: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9830: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9840: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9850: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
9860: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
9870: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
9880: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
9890: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
98a0: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
98b0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
98c0: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
98d0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
98e0: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
98f0: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
9900: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
9910: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
9920: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9930: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9940: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9950: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
9960: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
9970: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
9980: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
9990: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
99a0: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
99b0: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
99c0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
99d0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
99e0: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
99f0: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
9a00: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
9a10: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
9a20: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9a30: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9a40: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9a50: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9a60: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9a70: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9a80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9a90: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9aa0: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9ab0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9ac0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
9ad0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
9ae0: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
9af0: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
9b00: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
9b10: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9b20: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9b30: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9b40: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9b50: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9b60: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9b70: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9b80: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9b90: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9ba0: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9bb0: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9bc0: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9bd0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9be0: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9bf0: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9c00: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9c10: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9c20: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9c30: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9c40: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9c50: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9c60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9c70: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9c80: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9c90: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9ca0: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9cb0: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9cc0: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9cd0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9ce0: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9cf0: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9d00: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9d10: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9d20: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9d30: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9d40: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9d50: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9d60: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9d70: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9d80: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9d90: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9da0: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
9db0: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9dc0: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9dd0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9de0: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9df0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9e00: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9e10: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9e20: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9e30: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9e40: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9e50: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9e60: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9e70: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9e80: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9e90: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9ea0: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9eb0: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9ec0: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9ed0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9ee0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9ef0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9f00: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9f10: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9f20: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9f30: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9f40: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9f50: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9f60: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9f70: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9f80: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9f90: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9fa0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9fb0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9fc0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9fd0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
9fe0: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
9ff0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a000: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a010: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
a020: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a030: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a040: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a050: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a060: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a070: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
a080: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
a090: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
a0a0: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
a0b0: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
a0c0: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
a0d0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
a0e0: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
a0f0: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
a100: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a110: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
a120: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a130: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a140: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a150: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a160: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a170: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a180: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a190: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a1a0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a1b0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a1c0: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a1d0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a1e0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a1f0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a200: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a210: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a220: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a230: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a240: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a250: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a260: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a270: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a280: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a290: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a2a0: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a2b0: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a2c0: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a2d0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a2e0: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a2f0: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a300: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a310: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a320: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a330: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a340: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a350: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a360: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a370: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a380: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a390: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a3a0: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a3b0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a3c0: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a3d0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a3e0: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a3f0: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a400: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a410: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a420: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a430: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a440: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a450: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a460: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a470: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a480: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a490: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a4a0: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a4b0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a4c0: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a4d0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a4e0: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a4f0: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a500: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a510: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a520: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a530: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a540: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a550: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a560: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a570: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a580: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a590: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a5a0: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a5b0: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a5c0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a5d0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a5e0: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a5f0: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a600: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a610: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a620: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a630: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a640: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a650: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a660: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a670: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a680: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a690: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a6a0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a6b0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a6c0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a6d0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
a6e0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
a6f0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
a700: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a710: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a720: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a730: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a740: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a750: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a760: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a770: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a780: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a790: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a7a0: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a7b0: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a7c0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a7d0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a7e0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a7f0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a800: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a810: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a820: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a830: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a840: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a850: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a860: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a870: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a880: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a890: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a8a0: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a8b0: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a8c0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a8d0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a8e0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a8f0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a900: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a910: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a920: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a930: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a940: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a950: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a960: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a970: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a980: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a990: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a9a0: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
a9b0: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
a9c0: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
a9d0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a9e0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
a9f0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
aa00: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
aa10: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
aa20: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
aa30: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
aa40: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
aa50: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
aa60: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
aa70: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
aa80: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
aa90: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
aaa0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
aab0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
aac0: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
aad0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
aae0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
aaf0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
ab00: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
ab10: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
ab20: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
ab30: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
ab40: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
ab50: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
ab60: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
ab70: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
ab80: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
ab90: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aba0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
abb0: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
abc0: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
abd0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
abe0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
abf0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
ac00: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
ac10: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
ac20: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
ac30: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ac40: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
ac50: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
ac60: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
ac70: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
ac80: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
ac90: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
aca0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
acb0: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
acc0: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
acd0: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
ace0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
acf0: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
ad00: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
ad10: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
ad20: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
ad30: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
ad40: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
ad50: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
ad60: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
ad70: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
ad80: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
ad90: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
ada0: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
adb0: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
adc0: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
add0: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
ade0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
adf0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
ae00: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
ae10: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
ae20: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
ae30: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
ae40: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
ae50: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
ae60: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
ae70: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
ae80: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
ae90: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
aea0: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
aeb0: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
aec0: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
aed0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
aee0: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
aef0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
af00: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
af10: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
af20: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
af30: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
af40: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
af50: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
af60: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
af70: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
af80: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
af90: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
afa0: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
afb0: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
afc0: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
afd0: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
afe0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
aff0: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
b000: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
b010: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
b020: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
b030: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
b040: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
b050: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
b060: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
b070: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
b080: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
b090: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
b0a0: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
b0b0: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
b0c0: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
b0d0: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
b0e0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b0f0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
b100: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b110: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
b120: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b130: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
b140: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
b150: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
b160: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
b170: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
b180: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
b190: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b1a0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
b1b0: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
b1c0: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
b1d0: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
b1e0: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
b1f0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
b200: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
b210: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
b220: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
b230: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
b240: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
b250: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
b260: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
b270: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
b280: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
b290: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
b2a0: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
b2b0: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
b2c0: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
b2d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
b2e0: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
b2f0: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
b300: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
b310: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
b320: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
b330: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
b340: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b350: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
b360: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
b370: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
b380: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
b390: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
b3a0: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
b3b0: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
b3c0: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
b3d0: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
b3e0: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
b3f0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
b400: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
b410: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
b420: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
b430: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b440: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
b450: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
b460: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
b470: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
b480: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
b490: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
b4a0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
b4b0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
b4c0: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
b4d0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b4e0: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
b4f0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b500: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
b510: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ED]].** The [SQL
b520: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
b530: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  VED] file contro
b540: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
b550: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a   argument as a.*
b560: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
b570: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77  integer and it w
b580: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20  rites a boolean 
b590: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
b5a0: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  r depending.** o
b5b0: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
b5c0: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65   the file has be
b5d0: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65  en renamed, move
b5e0: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69  d, or deleted si
b5f0: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69  nce it.** was fi
b600: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  rst opened..**.*
b610: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </ul>.*/.#defi
b620: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b630: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
b640: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
b650: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
b660: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
b670: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
b680: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
b690: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
b6a0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
b6b0: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e  SQLITE_LAST_ERRN
b6c0: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  O               
b6d0: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
b6e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
b6f0: 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  _HINT           
b700: 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
b710: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
b720: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
b730: 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
b740: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
b750: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
b760: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
b770: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
b780: 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20  ITTED           
b790: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
b7a0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
b7b0: 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20  _RETRY          
b7c0: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
b7d0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
b7e0: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30  AL            10
b7f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b800: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20  FCNTL_OVERWRITE 
b810: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a               11.
b820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b830: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20  CNTL_VFSNAME    
b840: 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23              12.#
b850: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b860: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
b870: 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64  ERWRITE    13.#d
b880: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b890: 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TL_PRAGMA       
b8a0: 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65            14.#de
b8b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b8c0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20  L_BUSYHANDLER   
b8d0: 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66           15.#def
b8e0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b8f0: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20  _TEMPFILENAME   
b900: 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69          16.#defi
b910: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b920: 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20  MMAP_SIZE       
b930: 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e         18.#defin
b940: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
b950: 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20  RACE            
b960: 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65        19.#define
b970: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41   SQLITE_FCNTL_HA
b980: 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20  S_MOVED         
b990: 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20       20.#define 
b9a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
b9b0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
b9c0: 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53      21.#define S
b9d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
b9e0: 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20  IT_PHASETWO     
b9f0: 20 20 20 32 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     22../*.** CAP
ba00: 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e  I3REF: Mutex Han
ba10: 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75  dle.**.** The mu
ba20: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69  tex module withi
ba30: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73  n SQLite defines
ba40: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
ba50: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73   to be an.** abs
ba60: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61  tract type for a
ba70: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20   mutex object.  
ba80: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
ba90: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61  never looks.** a
baa0: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  t the internal r
bab0: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66  epresentation of
bac0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
bad0: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a  ex].  It only.**
bae0: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e   deals with poin
baf0: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  ters to the [sql
bb00: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65  ite3_mutex] obje
bb10: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65  ct..**.** Mutexe
bb20: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
bb30: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
bb40: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  ex_alloc()]..*/.
bb50: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
bb60: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c  qlite3_mutex sql
bb70: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a  ite3_mutex;../*.
bb80: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
bb90: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
bba0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
bbb0: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
bbc0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
bbd0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
bbe0: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
bbf0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
bc00: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
bc10: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
bc20: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
bc30: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
bc40: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
bc50: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
bc60: 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65  ile system".  Se
bc70: 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20  e.** the [VFS | 
bc80: 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  VFS documentatio
bc90: 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69  n] for further i
bca0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
bcb0: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
bcc0: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
bcd0: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
bce0: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
bcf0: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
bd00: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
bd10: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
bd20: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
bd30: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
bd40: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
bd50: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
bd60: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
bd70: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
bd80: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
bd90: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
bda0: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
bdb0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
bdc0: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
bdd0: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
bde0: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
bdf0: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
be00: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
be10: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
be20: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
be30: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
be40: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
be50: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
be60: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
be70: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
be80: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
be90: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
bea0: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
beb0: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
bec0: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
bed0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
bee0: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
bef0: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
bf00: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
bf10: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
bf20: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
bf30: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
bf40: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
bf50: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
bf60: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
bf70: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
bf80: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
bf90: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
bfa0: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
bfb0: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
bfc0: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
bfd0: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
bfe0: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
bff0: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
c000: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
c010: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
c020: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
c030: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
c040: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
c050: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
c060: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
c070: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
c080: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
c090: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
c0a0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
c0b0: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
c0c0: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
c0d0: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
c0e0: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
c0f0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
c100: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
c110: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
c120: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
c130: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
c140: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
c150: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
c160: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
c170: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
c180: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
c190: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
c1a0: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
c1b0: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
c1c0: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  modules..**.** [
c1d0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
c1e0: 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  en]].** ^SQLite 
c1f0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
c200: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
c210: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
c220: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20  .** is either a 
c230: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
c240: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a  string obtained.
c250: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74  ** from xFullPat
c260: 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20  hname() with an 
c270: 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20  optional suffix 
c280: 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20  added..** ^If a 
c290: 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20  suffix is added 
c2a0: 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  to the zFilename
c2b0: 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77   parameter, it w
c2c0: 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f  ill.** consist o
c2d0: 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63  f a single "-" c
c2e0: 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65  haracter followe
c2f0: 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61  d by no more tha
c300: 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d  n.** 11 alphanum
c310: 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20  eric and/or "-" 
c320: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e  characters..** ^
c330: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
c340: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
c350: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
c360: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
c370: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
c380: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
c390: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66  lled. Because of
c3a0: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
c3b0: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntence,.** the [
c3c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
c3d0: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
c3e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
c3f0: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
c400: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
c410: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
c420: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
c430: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
c440: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
c450: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  to xOpen is a NU
c460: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
c470: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
c480: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d  vent its own tem
c490: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
c4a0: 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e  the file.  ^When
c4b0: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69  ever the .** xFi
c4c0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
c4d0: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c   is NULL it will
c4e0: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73   also be the cas
c4f0: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c  e that the.** fl
c500: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69  ags parameter wi
c510: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ll include [SQLI
c520: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
c530: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  CLOSE]..**.** Th
c540: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
c550: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c   to xOpen() incl
c560: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65  udes all bits se
c570: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67  t in.** the flag
c580: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  s argument to [s
c590: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
c5a0: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74  ].  Or if [sqlit
c5b0: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72  e3_open()].** or
c5c0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
c5d0: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65  ()] is used, the
c5e0: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73  n flags includes
c5f0: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51   at least.** [SQ
c600: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
c610: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
c620: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a  PEN_CREATE]. .**
c630: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e   If xOpen() open
c640: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e  s a file read-on
c650: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20  ly then it sets 
c660: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a  *pOutFlags to.**
c670: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
c680: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e  _OPEN_READONLY].
c690: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20    Other bits in 
c6a0: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62  *pOutFlags may b
c6b0: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53  e set..**.** ^(S
c6c0: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20  QLite will also 
c6d0: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
c6e0: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
c6f0: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
c700: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67   call, depending
c710: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62   on the object b
c720: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a  eing opened:.**.
c730: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
c740: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
c750: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
c760: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
c770: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
c780: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c790: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
c7a0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c7b0: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
c7c0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c7d0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
c7e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c7f0: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
c800: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
c810: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
c820: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
c830: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c840: 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  WAL].** </ul>)^.
c850: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
c860: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
c870: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
c880: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
c890: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  to.** change the
c8a0: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
c8b0: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
c8c0: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
c8d0: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
c8e0: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
c8f0: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
c900: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
c910: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
c920: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
c930: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
c940: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
c950: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
c960: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
c970: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
c980: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
c990: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
c9a0: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52  n.** SQLITE_IOER
c9b0: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  R.  Or the imple
c9c0: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
c9d0: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61  recognize that a
c9e0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
c9f0: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20  e will be doing 
ca00: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63  page-aligned sec
ca10: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72  tor reads and wr
ca20: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d  ites in a random
ca30: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65  .** order and se
ca40: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62  t up its I/O sub
ca50: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67  system according
ca60: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ly..**.** SQLite
ca70: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
ca80: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
ca90: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
caa0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a  e xOpen method:.
cab0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
cac0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
cad0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
cae0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
caf0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
cb00: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
cb10: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
cb20: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
cb30: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
cb40: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
cb50: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
cb60: 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20  s closed.  ^The 
cb70: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
cb80: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77  ETEONCLOSE].** w
cb90: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54  ill be set for T
cba0: 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e  EMP databases an
cbb0: 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73  d their journals
cbc0: 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64  , transient.** d
cbd0: 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75  atabases, and su
cbe0: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
cbf0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
cc00: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
cc10: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  ag is always use
cc20: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e  d in conjunction
cc30: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
cc40: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
cc50: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72  ] flag, which ar
cc60: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a  e both directly.
cc70: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20  ** analogous to 
cc80: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f  the O_EXCL and O
cc90: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20  _CREAT flags of 
cca0: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29  the POSIX open()
ccb0: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51  .** API.  The SQ
ccc0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
ccd0: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70  IVE flag, when p
cce0: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a  aired with the .
ccf0: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ** SQLITE_OPEN_C
cd00: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74  REATE, is used t
cd10: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
cd20: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61  file should alwa
cd30: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64  ys.** be created
cd40: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73  , and that it is
cd50: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20   an error if it 
cd60: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a  already exists..
cd70: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c  ** It is <i>not<
cd80: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69  /i> used to indi
cd90: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68  cate the file sh
cda0: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a  ould be opened .
cdb0: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65  ** for exclusive
cdc0: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e   access..**.** ^
cdd0: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
cde0: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
cdf0: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  y are allocated 
ce00: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20  by SQLite.** to 
ce10: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
ce20: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
ce30: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
ce40: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
ce50: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68  nt to xOpen.  Th
ce60: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
ce70: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
ce80: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
ce90: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
cea0: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
ceb0: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74  t in.  Note that
cec0: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65  .** the xOpen me
ced0: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68  thod must set th
cee0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
cef0: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65  Methods to eithe
cf00: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71  r.** a valid [sq
cf10: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
cf20: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e  ] object or to N
cf30: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74  ULL.  xOpen must
cf40: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e   do.** this even
cf50: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
cf60: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65  ls.  SQLite expe
cf70: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c  cts that the sql
cf80: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
cf90: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69  ds.** element wi
cfa0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65  ll be valid afte
cfb0: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20  r xOpen returns 
cfc0: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
cfd0: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20  e success.** or 
cfe0: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78  failure of the x
cff0: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  Open call..**.**
d000: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
d010: 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65  Access]].** ^The
d020: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
d030: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
d040: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
d050: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
d060: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
d070: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
d080: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
d090: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
d0a0: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
d0b0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
d0c0: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
d0d0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
d0e0: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
d0f0: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
d100: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
d110: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
d120: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
d130: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
d140: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
d150: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
d160: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
d170: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
d180: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
d190: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
d1a0: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20  ame.  The exact 
d1b0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
d1c0: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
d1d0: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61  also passed as a
d1e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f   parameter to bo
d1f0: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20  th  methods. If 
d200: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
d210: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
d220: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
d230: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
d240: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
d250: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
d260: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
d270: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
d280: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
d290: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
d2a0: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
d2b0: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
d2c0: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
d2d0: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
d2e0: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
d2f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
d300: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
d310: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65  (), xCurrentTime
d320: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
d330: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69  TimeInt64().** i
d340: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f  nterfaces are no
d350: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
d360: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
d370: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
d380: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
d390: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
d3a0: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
d3b0: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
d3c0: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
d3d0: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
d3e0: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
d3f0: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
d400: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
d410: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
d420: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
d430: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
d440: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
d450: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
d460: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
d470: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
d480: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
d490: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
d4a0: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
d4b0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
d4c0: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
d4d0: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e  n.  ^The xCurren
d4e0: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
d4f0: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
d500: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
d510: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
d520: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a  te and time as.*
d530: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  * a floating poi
d540: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68  nt value..** ^Th
d550: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
d560: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74  t64() method ret
d570: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65  urns, as an inte
d580: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a  ger, the Julian.
d590: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75  ** Day Number mu
d5a0: 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30  ltiplied by 8640
d5b0: 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72  0000 (the number
d5c0: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
d5d0: 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75   in .** a 24-hou
d5e0: 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51  r day).  .** ^SQ
d5f0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
d600: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
d610: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20  t64() method to 
d620: 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a  get the current.
d630: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  ** date and time
d640: 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20   if that method 
d650: 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66  is available (if
d660: 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f   iVersion is 2 o
d670: 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e  r .** greater an
d680: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  d the function p
d690: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
d6a0: 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c  LL) and will fal
d6b0: 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75  l back.** to xCu
d6c0: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78  rrentTime() if x
d6d0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
d6e0: 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  () is unavailabl
d6f0: 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53  e..**.** ^The xS
d700: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
d710: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xGetSystemCall()
d720: 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65  , and xNestSyste
d730: 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  mCall() interfac
d740: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73  es.** are not us
d750: 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65  ed by the SQLite
d760: 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70   core.  These op
d770: 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65  tional interface
d780: 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a  s are provided.*
d790: 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20  * by some VFSes 
d7a0: 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65  to facilitate te
d7b0: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53  sting of the VFS
d7c0: 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69   code. By overri
d7d0: 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20  ding .** system 
d7e0: 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74  calls with funct
d7f0: 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63  ions under its c
d800: 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70  ontrol, a test p
d810: 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69  rogram can.** si
d820: 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e  mulate faults an
d830: 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f  d error conditio
d840: 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74  ns that would ot
d850: 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69  herwise be diffi
d860: 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73  cult.** or impos
d870: 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e  sible to induce.
d880: 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73    The set of sys
d890: 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63  tem calls that c
d8a0: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
d8b0: 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20  .** varies from 
d8c0: 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68  one VFS to anoth
d8d0: 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65  er, and from one
d8e0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
d8f0: 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a  same VFS to the.
d900: 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
d910: 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
d920: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
d930: 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65   must be prepare
d940: 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20  d for any.** or 
d950: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74  all of these int
d960: 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55  erfaces to be NU
d970: 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20  LL or for their 
d980: 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e  behavior to chan
d990: 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72  ge.** from one r
d9a0: 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
d9b0: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
d9c0: 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d  s must not attem
d9d0: 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20  pt to access.** 
d9e0: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74  any of these met
d9f0: 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72  hods if the iVer
da00: 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20  sion of the VFS 
da10: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a  is less than 3..
da20: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
da30: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
da40: 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64  lite3_vfs;.typed
da50: 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
da60: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76  3_syscall_ptr)(v
da70: 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c  oid);.struct sql
da80: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
da90: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
daa0: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
dab0: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
dac0: 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20  r (currently 3) 
dad0: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
dae0: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
daf0: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
db00: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
db10: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
db20: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
db30: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
db40: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
db50: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
db60: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
db70: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
db80: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
db90: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
dba0: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
dbb0: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
dbc0: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
dbd0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
dbe0: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
dbf0: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
dc00: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
dc10: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
dc20: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
dc30: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
dc40: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
dc50: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
dc60: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
dc70: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
dc80: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
dc90: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
dca0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
dcb0: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
dcc0: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
dcd0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
dce0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
dcf0: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
dd00: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
dd10: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
dd20: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
dd30: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
dd40: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
dd50: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
dd60: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
dd70: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
dd80: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
dd90: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
dda0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
ddb0: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
ddc0: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
ddd0: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
dde0: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
ddf0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
de00: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
de10: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
de20: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
de30: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
de40: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
de50: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
de60: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
de70: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
de80: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
de90: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
dea0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
deb0: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
dec0: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
ded0: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
dee0: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
def0: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
df00: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
df10: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
df20: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20  re in version 1 
df30: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
df40: 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65  s object.  ** de
df50: 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65  finition.  Those
df60: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65   that follow are
df70: 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f   added in versio
df80: 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a  n 2 or later.  *
df90: 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  /.  int (*xCurre
dfa0: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c  ntTimeInt64)(sql
dfb0: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74  ite3_vfs*, sqlit
dfc0: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a  e3_int64*);.  /*
dfd0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
dfe0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
dff0: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20  ersions 1 and 2 
e000: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
e010: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54  s object..  ** T
e020: 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66  hose below are f
e030: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64  or version 3 and
e040: 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20   greater..  */. 
e050: 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65   int (*xSetSyste
e060: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
e070: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e080: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
e090: 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20  syscall_ptr);.  
e0a0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
e0b0: 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d  ptr (*xGetSystem
e0c0: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
e0d0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e0e0: 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20  zName);.  const 
e0f0: 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73  char *(*xNextSys
e100: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
e110: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e120: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a  r *zName);.  /*.
e130: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
e140: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
e150: 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68  rsions 1 through
e160: 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   3 of the sqlite
e170: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
e180: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
e190: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
e1a0: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
e1b0: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
e1c0: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
e1d0: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
e1e0: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
e1f0: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
e200: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
e210: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
e220: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
e230: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
e240: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
e250: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
e260: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
e270: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
e280: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
e290: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
e2a0: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
e2b0: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
e2c0: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
e2d0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
e2e0: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
e2f0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
e300: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
e310: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e320: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
e330: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
e340: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
e350: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
e360: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
e370: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
e380: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
e390: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
e3a0: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
e3b0: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
e3c0: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
e3d0: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
e3e0: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
e3f0: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
e400: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
e410: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
e420: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
e430: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
e440: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
e450: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
e460: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
e470: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
e480: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
e490: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
e4a0: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
e4b0: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
e4c0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
e4d0: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
e4e0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
e4f0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
e500: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
e510: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
e520: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
e530: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
e540: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
e550: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
e560: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
e570: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
e580: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
e590: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
e5a0: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
e5b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
e5c0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
e5d0: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
e5e0: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
e5f0: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
e600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
e610: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
e620: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
e630: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
e640: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
e650: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
e660: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
e670: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
e680: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
e690: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
e6a0: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
e6b0: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
e6c0: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
e6d0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
e6e0: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
e6f0: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
e700: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
e710: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
e720: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
e730: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
e740: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
e750: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
e760: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
e770: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
e780: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
e790: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
e7a0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
e7b0: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
e7c0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
e7d0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
e7e0: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
e7f0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
e800: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
e810: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
e820: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
e830: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
e840: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
e850: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
e860: 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   no the correspo
e870: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
e880: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
e890: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
e8a0: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
e8b0: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
e8c0: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
e8d0: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
e8e0: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
e8f0: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
e900: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
e910: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
e920: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e930: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
e940: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
e950: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
e960: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
e970: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
e980: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
e990: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
e9a0: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
e9b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
e9c0: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
e9d0: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
e9e0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
e9f0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
ea00: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
ea10: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
ea20: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
ea30: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
ea40: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
ea50: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
ea60: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
ea70: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
ea80: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
ea90: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
eaa0: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
eab0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
eac0: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
ead0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
eae0: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
eaf0: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
eb00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
eb10: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
eb20: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
eb30: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
eb40: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
eb50: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
eb60: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
eb70: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
eb80: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
eb90: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
eba0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ebb0: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
ebc0: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
ebd0: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
ebe0: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
ebf0: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
ec00: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
ec10: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
ec20: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
ec30: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
ec40: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
ec50: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
ec60: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
ec70: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
ec80: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
ec90: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
eca0: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
ecb0: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
ecc0: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
ecd0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
ece0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
ecf0: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
ed00: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
ed10: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
ed20: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
ed30: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
ed40: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
ed50: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
ed60: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
ed70: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ed80: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
ed90: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
eda0: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
edb0: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
edc0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
edd0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
ede0: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
edf0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
ee00: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
ee10: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
ee20: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
ee30: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
ee40: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
ee50: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ee60: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
ee70: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
ee80: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
ee90: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
eea0: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
eeb0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
eec0: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
eed0: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
eee0: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
eef0: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
ef00: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
ef10: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
ef20: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
ef30: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
ef40: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
ef50: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
ef60: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
ef70: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
ef80: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ef90: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
efa0: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
efb0: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
efc0: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
efd0: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
efe0: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
eff0: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
f000: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
f010: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
f020: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
f030: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
f040: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
f050: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
f060: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
f070: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
f080: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
f090: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
f0a0: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
f0b0: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
f0c0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
f0d0: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
f0e0: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
f0f0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
f100: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
f110: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
f120: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
f130: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
f140: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
f150: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f160: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
f170: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
f180: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
f190: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
f1a0: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
f1b0: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
f1c0: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
f1d0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
f1e0: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
f1f0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
f200: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
f210: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f220: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
f230: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
f240: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
f250: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
f260: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
f270: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
f280: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
f290: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
f2a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f2b0: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
f2c0: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
f2d0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
f2e0: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
f2f0: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
f300: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
f310: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
f320: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
f330: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
f340: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
f350: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
f360: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
f370: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
f380: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
f390: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
f3a0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
f3b0: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
f3c0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
f3d0: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
f3e0: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
f3f0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f400: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
f410: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
f420: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
f430: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
f440: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
f450: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
f460: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
f470: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
f480: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
f490: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
f4a0: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
f4b0: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
f4c0: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
f4d0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f4e0: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
f4f0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
f500: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
f510: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
f520: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
f530: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
f540: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
f550: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
f560: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
f570: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
f580: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
f590: 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
f5a0: 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
f5b0: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
f5c0: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
f5d0: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
f5e0: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
f5f0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
f600: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
f610: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
f620: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
f630: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
f640: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
f650: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
f660: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f670: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
f680: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
f690: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
f6a0: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
f6b0: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
f6c0: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
f6d0: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
f6e0: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
f6f0: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
f700: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
f710: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
f720: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
f730: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
f740: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
f750: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
f760: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
f770: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
f780: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
f790: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f7a0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
f7b0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
f7c0: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
f7d0: 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
f7e0: 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
f7f0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
f800: 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
f810: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
f820: 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
f830: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f840: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
f850: 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
f860: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f870: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
f880: 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
f890: 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
f8a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
f8b0: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
f8c0: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
f8d0: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
f8e0: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
f8f0: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
f900: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
f910: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
f920: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
f930: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
f940: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
f950: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
f960: 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
f970: 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
f980: 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
f990: 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
f9a0: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
f9b0: 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
f9c0: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
f9d0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
f9e0: 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
f9f0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
fa00: 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
fa10: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
fa20: 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
fa30: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
fa40: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
fa50: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
fa60: 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
fa70: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
fa80: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
fa90: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
faa0: 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
fab0: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
fac0: 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
fad0: 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
fae0: 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
faf0: 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  lure..*/.SQLITE_
fb00: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
fb10: 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
fb20: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
fb30: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fb40: 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  n(void);.SQLITE_
fb50: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
fb60: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53  os_init(void);.S
fb70: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
fb80: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
fb90: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
fba0: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
fbb0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
fbc0: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
fbd0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
fbe0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
fbf0: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
fc00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
fc10: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
fc20: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
fc30: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
fc40: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
fc50: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
fc60: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
fc70: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
fc80: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
fc90: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
fca0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
fcb0: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
fcc0: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
fcd0: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
fce0: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
fcf0: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
fd00: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
fd10: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
fd20: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
fd30: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
fd40: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
fd50: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
fd60: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
fd70: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
fd80: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
fd90: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
fda0: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
fdb0: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
fdc0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
fdd0: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
fde0: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
fdf0: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
fe00: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
fe10: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
fe20: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
fe30: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
fe40: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
fe50: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
fe60: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
fe70: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
fe80: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fe90: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
fea0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
feb0: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
fec0: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
fed0: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
fee0: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
fef0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
ff00: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
ff10: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
ff20: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
ff30: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
ff40: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
ff50: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
ff60: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
ff70: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
ff80: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
ff90: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
ffa0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
ffb0: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
ffc0: 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
ffd0: 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
ffe0: 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
fff0: 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
10000 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
10010 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
10020 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
10030 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
10040 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
10050 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
10060 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
10070 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
10080 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
10090 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
100a0 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
100b0 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
100c0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
100d0 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
100e0 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
100f0 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
10100 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
10110 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
10120 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
10130 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
10140 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  e]..*/.SQLITE_AP
10150 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
10160 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
10170 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10180 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
10190 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
101a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
101b0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e  3_db_config() in
101c0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
101d0 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72  to make configur
101e0 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
101f0 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20   to a [database 
10200 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
10210 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73  e interface is s
10220 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71  imilar to.** [sq
10230 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
10240 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20  except that the 
10250 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f  changes apply to
10260 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61   a single.** [da
10270 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10280 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e  n] (specified in
10290 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
102a0 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent)..**.** The 
102b0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
102c0 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
102d0 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69  nfig(D,V,...)  i
102e0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
102f0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
10300 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  IDE | configurat
10310 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69  ion verb] - an i
10320 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20  nteger code .** 
10330 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77  that indicates w
10340 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68  hat aspect of th
10350 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
10360 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
10370 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20   configured..** 
10380 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
10390 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64  ents vary depend
103a0 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69  ing on the confi
103b0 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a  guration verb..*
103c0 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73  *.** ^Calls to s
103d0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
103e0 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
103f0 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  _OK if and only 
10400 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69  if.** the call i
10410 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63  s considered suc
10420 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  cessful..*/.SQLI
10430 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
10440 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
10450 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
10460 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
10470 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
10480 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
10490 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
104a0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
104b0 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
104c0 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
104d0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
104e0 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
104f0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
10500 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
10510 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
10520 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
10530 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
10540 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
10550 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
10560 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
10570 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
10580 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
10590 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
105a0 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
105b0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
105c0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
105d0 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49  MALLOC] or [SQLI
105e0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
105f0 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72  LOC].  .** By cr
10600 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
10610 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
10620 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
10630 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
10640 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
10650 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a  CONFIG_MALLOC]).
10660 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  ** during config
10670 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c  uration, an appl
10680 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
10690 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
106a0 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
106b0 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
106c0 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  m for SQLite to 
106d0 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
106e0 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65  ts.** dynamic me
106f0 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
10700 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
10710 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65  te comes with se
10720 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20  veral [built-in 
10730 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10740 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70  s].** that are p
10750 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
10760 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
10770 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
10780 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
10790 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
107a0 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
107b0 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
107c0 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
107d0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
107e0 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
107f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10800 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
10810 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
10820 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
10830 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
10840 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
10850 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
10860 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
10870 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
10880 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
10890 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
108a0 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
108b0 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
108c0 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
108d0 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
108e0 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
108f0 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
10900 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61  he xMalloc, xRea
10910 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20  lloc, and xFree 
10920 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72  methods must wor
10930 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61  k like the.** ma
10940 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
10950 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
10960 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
10970 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
10980 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  ry..** ^SQLite g
10990 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
109a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
109b0 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f  nt to.** xReallo
109c0 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61  c is always a va
109d0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
109e0 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
109f0 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20  xRoundup..**.** 
10a00 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
10a10 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
10a20 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
10a30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
10a40 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
10a50 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
10a60 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
10a70 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
10a80 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
10a90 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
10aa0 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
10ab0 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
10ac0 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
10ad0 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
10ae0 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
10af0 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
10b00 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
10b10 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
10b20 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
10b30 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
10b40 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
10b50 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
10b60 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
10b70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
10b80 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
10b90 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
10ba0 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
10bb0 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
10bc0 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
10bd0 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
10be0 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65  wer of 2..** Eve
10bf0 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
10c00 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d  tion request com
10c10 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b  ing in through [
10c20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
10c30 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
10c40 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73  _realloc()] firs
10c50 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70  t calls xRoundup
10c60 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72  .  If xRoundup r
10c70 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68  eturns 0, .** th
10c80 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f  at causes the co
10c90 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f  rresponding memo
10ca0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
10cb0 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   fail..**.** The
10cc0 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
10cd0 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
10ce0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
10cf0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a   For example,.**
10d00 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
10d10 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
10d20 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
10d30 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
10d40 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
10d50 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
10d60 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
10d70 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
10d80 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
10d90 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
10da0 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
10db0 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
10dc0 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
10dd0 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
10de0 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
10df0 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
10e00 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
10e10 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
10e20 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
10e30 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
10e40 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
10e50 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
10e60 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
10e70 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
10e80 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
10e90 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
10ea0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
10eb0 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
10ec0 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
10ed0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
10ee0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10ef0 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
10f00 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
10f10 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
10f20 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
10f30 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
10f40 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
10f50 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
10f60 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
10f70 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
10f80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
10f90 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
10fa0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
10fb0 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
10fc0 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
10fd0 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
10fe0 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
10ff0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
11000 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
11010 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
11020 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
11030 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
11040 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
11050 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
11060 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
11070 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
11080 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
11090 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
110a0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
110b0 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
110c0 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
110d0 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
110e0 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
110f0 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
11100 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
11110 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
11120 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
11130 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
11140 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
11150 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
11160 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
11170 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
11180 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
11190 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
111a0 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
111b0 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
111c0 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
111d0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
111e0 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
111f0 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
11200 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
11210 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
11220 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
11230 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
11240 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
11250 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
11260 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
11270 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
11280 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
11290 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
112a0 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
112b0 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
112c0 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
112d0 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
112e0 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
112f0 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
11300 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
11310 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
11320 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
11330 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11340 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
11350 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
11360 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
11370 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
11380 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
11390 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
113a0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
113b0 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
113c0 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
113d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
113e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
113f0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
11400 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
11410 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11420 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
11430 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
11440 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11450 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
11460 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
11470 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
11480 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11490 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
114a0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
114b0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
114c0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
114d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
114e0 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
114f0 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
11500 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
11510 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
11520 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
11530 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11540 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
11550 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
11560 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
11570 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
11580 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
11590 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
115a0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
115b0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
115c0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
115d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
115e0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
115f0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
11600 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11610 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
11620 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11630 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
11640 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
11650 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
11660 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
11670 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
11680 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
11690 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
116a0 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
116b0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
116c0 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
116d0 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
116e0 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
116f0 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
11700 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
11710 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
11720 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
11730 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11740 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
11750 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
11760 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
11770 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
11780 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
11790 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
117a0 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
117b0 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
117c0 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
117d0 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
117e0 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
117f0 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
11800 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
11810 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
11820 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
11830 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
11840 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
11850 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
11860 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11870 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
11880 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
11890 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
118a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
118b0 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
118c0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
118d0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
118e0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
118f0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
11900 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
11910 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
11920 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
11930 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
11940 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
11950 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
11960 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
11970 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11980 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
11990 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
119a0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
119b0 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
119c0 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
119d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
119e0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
119f0 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
11a00 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
11a10 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
11a20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
11a30 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
11a40 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
11a50 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
11a60 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
11a70 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
11a80 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
11a90 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
11aa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11ab0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
11ac0 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
11ad0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
11ae0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
11af0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
11b00 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
11b10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
11b20 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
11b30 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
11b40 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
11b50 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
11b60 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
11b70 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11b80 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
11b90 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
11ba0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
11bb0 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
11bc0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
11bd0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11be0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
11bf0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
11c00 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
11c10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
11c20 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
11c30 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
11c40 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
11c50 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
11c60 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11c70 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
11c80 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
11c90 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
11ca0 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
11cb0 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
11cc0 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
11cd0 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
11ce0 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
11cf0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11d00 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
11d10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
11d20 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
11d30 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
11d40 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
11d50 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
11d60 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
11d70 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
11d80 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
11d90 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
11da0 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
11db0 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
11dc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
11dd0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
11de0 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
11df0 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
11e00 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
11e10 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
11e20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11e30 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
11e40 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
11e50 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
11e60 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
11e70 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
11e80 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
11e90 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
11ea0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
11eb0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
11ec0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
11ed0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
11ee0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
11ef0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
11f00 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
11f10 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
11f20 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
11f30 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
11f40 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
11f50 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
11f60 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
11f70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
11f80 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
11f90 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
11fa0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11fb0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
11fc0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11fd0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
11fe0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
11ff0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
12000 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
12010 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
12020 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
12030 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
12040 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12050 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
12060 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
12070 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
12080 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
12090 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
120a0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
120b0 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
120c0 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
120d0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
120e0 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
120f0 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
12100 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
12110 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
12120 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
12130 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12140 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12150 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
12160 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12170 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
12180 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12190 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
121a0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
121b0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
121c0 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
121d0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
121e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
121f0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
12200 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
12210 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
12220 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12230 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12240 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  re.  The [sqlite
12250 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
12260 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
12270 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
12280 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
12290 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
122a0 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
122b0 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
122c0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
122d0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
122e0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
122f0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
12300 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
12310 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
12320 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12330 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
12340 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
12350 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
12360 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
12370 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
12380 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
12390 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
123a0 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
123b0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
123c0 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
123d0 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
123e0 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
123f0 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
12400 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
12410 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
12420 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
12430 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
12440 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  ** statistics. ^
12450 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
12460 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
12470 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c  cs are disabled,
12480 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69   the .** followi
12490 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ng SQLite interf
124a0 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d  aces become non-
124b0 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20  operational:.** 
124c0 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e    <ul>.**   <li>
124d0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
124e0 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c  _used()].**   <l
124f0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
12500 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a  ry_highwater()].
12510 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
12520 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
12530 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  it64()].**   <li
12540 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
12550 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29  s()].**   </ul>)
12560 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c  ^.** ^Memory all
12570 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
12580 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  cs are enabled b
12590 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73  y default unless
125a0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
125b0 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
125c0 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
125d0 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63  TATUS]=0 in whic
125e0 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a  h case memory.**
125f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
12600 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
12610 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
12620 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
12630 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
12640 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c  CRATCH]] <dt>SQL
12650 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12660 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
12670 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
12680 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
12690 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
126a0 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
126b0 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
126c0 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
126d0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
126e0 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
126f0 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
12700 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
12710 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
12720 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
12730 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
12740 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
12750 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
12760 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
12770 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
12780 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
12790 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
127a0 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  ns (N).  The sz.
127b0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
127c0 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
127d0 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72  f 16..** The fir
127e0 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
127f0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
12800 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
12810 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
12820 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
12830 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
12840 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
12850 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
12860 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66  two scratch buff
12870 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20  ers per thread. 
12880 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20   So.** N should 
12890 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20  be set to twice 
128a0 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
128b0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
128c0 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69  hreads..** ^SQLi
128d0 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65  te will never re
128e0 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20  quire a scratch 
128f0 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
12900 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69  ore than 6.** ti
12910 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
12920 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20   page size. ^If 
12930 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
12940 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  ds additional.**
12950 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
12960 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
12970 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
12980 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12990 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
129a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
129b0 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
129c0 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
129d0 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e  ory needed.</dd>
129e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
129f0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
12a00 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12a10 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
12a20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
12a30 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
12a40 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
12a50 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
12a60 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
12a70 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  r.** the databas
12a80 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
12a90 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
12aa0 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
12ab0 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  ntation.  .** Th
12ac0 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
12ad0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
12ae0 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
12af0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
12b00 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
12b10 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
12b20 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
12b30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
12b40 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54  HE2 option..** T
12b50 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
12b60 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
12b70 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74   option: A point
12b80 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69  er to 8-byte ali
12b90 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  gned.** memory, 
12ba0 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
12bb0 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
12bc0 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
12bd0 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
12be0 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
12bf0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
12c00 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
12c10 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
12c20 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
12c30 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
12c40 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75  2 and 32768) plu
12c50 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61  s a little extra
12c60 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
12c70 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
12c80 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65  page header size
12c90 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74   is 20 to 40 byt
12ca0 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a  es depending on.
12cb0 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68  ** the host arch
12cc0 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69  itecture.  ^It i
12cd0 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
12ce0 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
12cf0 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20  d memory,.** to 
12d00 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65  make sz a little
12d10 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65   too large.  The
12d20 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
12d30 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20  nt should point 
12d40 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  to an allocation
12d50 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
12d60 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
12d70 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
12d80 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  ll use the memor
12d90 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  y provided by th
12da0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
12db0 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a   to satisfy its.
12dc0 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20  ** memory needs 
12dd0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20  for the first N 
12de0 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64  pages that it ad
12df0 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49  ds to cache.  ^I
12e00 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
12e10 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
12e20 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
12e30 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
12e40 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
12e50 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
12e60 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
12e70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
12e80 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
12e90 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a   storage space..
12ea0 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69  ** The pointer i
12eb0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
12ec0 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20  ment must.** be 
12ed0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
12ee0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72  byte boundary or
12ef0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
12f00 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
12f10 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  * will be undefi
12f20 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
12f30 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12f40 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
12f50 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
12f60 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
12f70 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
12f80 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
12f90 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
12fa0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
12fb0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
12fc0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
12fd0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
12fe0 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
12ff0 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
13000 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
13010 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
13020 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
13030 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
13040 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
13050 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61  nts: An 8-byte a
13060 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
13070 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
13080 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
13090 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
130a0 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
130b0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
130c0 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
130d0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
130e0 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
130f0 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
13100 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
13110 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
13120 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
13130 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
13140 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
13150 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
13160 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
13170 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
13180 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
13190 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
131a0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
131b0 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
131c0 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68  ot NULL and eith
131d0 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
131e0 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a  E_MEMSYS3] or.**
131f0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
13200 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66  MEMSYS5] are def
13210 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61  ined, then the a
13220 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
13230 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69  y.** allocator i
13240 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e  s engaged to han
13250 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74  dle all of SQLit
13260 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  es memory alloca
13270 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54  tion needs..** T
13280 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
13290 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
132a0 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c  nter) must be al
132b0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
132c0 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f  te.** boundary o
132d0 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
132e0 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20  avior of SQLite 
132f0 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
13300 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75  d..** The minimu
13310 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
13320 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32  e is capped at 2
13330 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65  **12. Reasonable
13340 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74   values.** for t
13350 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
13360 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32  ation size are 2
13370 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38  **5 through 2**8
13380 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13390 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
133a0 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
133b0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
133c0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
133d0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
133e0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
133f0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
13400 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
13410 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
13420 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13430 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
13440 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
13450 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
13460 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
13470 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
13480 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
13490 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
134a0 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
134b0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
134c0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
134d0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  opy of the.** co
134e0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
134f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
13500 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
13510 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
13520 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
13530 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
13540 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
13550 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
13560 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
13570 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
13580 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
13590 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
135a0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
135b0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
135c0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
135d0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
135e0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
135f0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
13600 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
13610 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
13620 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
13630 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
13640 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
13650 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
13660 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13670 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
13680 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13690 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
136a0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
136b0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
136c0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
136d0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
136e0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
136f0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
13700 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13710 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
13720 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
13730 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
13740 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
13750 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
13760 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
13770 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
13780 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
13790 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
137a0 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
137b0 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
137c0 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
137d0 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
137e0 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
137f0 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
13800 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
13810 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
13820 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
13830 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
13840 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
13850 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
13860 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
13870 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
13880 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
13890 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
138a0 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
138b0 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
138c0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
138d0 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
138e0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
138f0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
13900 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
13910 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
13920 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13930 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
13940 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
13950 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13960 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
13970 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c  KASIDE]] <dt>SQL
13980 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
13990 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
139a0 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
139b0 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
139c0 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
139d0 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  ne the default.*
139e0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
139f0 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b  ion for the look
13a00 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
13a10 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a  ocator on each.*
13a20 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
13a30 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69  ection].  The fi
13a40 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
13a50 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
13a60 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
13a70 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
13a80 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
13a90 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
13aa0 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
13ab0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
13ac0 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54  nnection.)^  ^(T
13ad0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
13ae0 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c  the.** <i>defaul
13af0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
13b00 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
13b10 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
13b20 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f  SIDE].** verb to
13b30 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
13b40 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
13b50 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
13b60 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
13b70 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
13b80 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
13b90 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
13ba0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13bb0 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c  NFIG_PCACHE2]] <
13bc0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13bd0 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  _PCACHE2</dt>.**
13be0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
13bf0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
13c00 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
13c10 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
13c20 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33  o.** an [sqlite3
13c30 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
13c40 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
13c50 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
13c60 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
13c70 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  * to a custom pa
13c80 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
13c90 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c  ntation.)^  ^SQL
13ca0 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
13cb0 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63   of the.** objec
13cc0 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f  t and uses it fo
13cd0 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
13ce0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
13cf0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13d00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
13d10 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
13d20 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
13d30 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
13d40 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
13d50 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13d60 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13d70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13d80 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
13d90 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
13da0 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
13db0 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72  opies of the cur
13dc0 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63  rent.** page cac
13dd0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
13de0 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
13df0 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
13e00 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13e10 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
13e20 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
13e30 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53  t>.** <dd> The S
13e40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
13e50 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
13e60 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65  to configure the
13e70 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61   SQLite.** globa
13e80 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a  l [error log]..*
13e90 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  * (^The SQLITE_C
13ea0 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
13eb0 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
13ec0 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
13ed0 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
13ee0 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
13ef0 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
13f00 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
13f10 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
13f20 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
13f30 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
13f40 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
13f50 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
13f60 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
13f70 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
13f80 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
13f90 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
13fa0 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
13fb0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
13fc0 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
13fd0 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
13fe0 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
13ff0 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
14000 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
14010 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
14020 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
14030 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
14040 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
14050 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14060 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
14070 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
14080 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
14090 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
140a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
140b0 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
140c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
140d0 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
140e0 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
140f0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
14100 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
14110 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
14120 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
14130 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
14140 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
14150 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
14160 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
14170 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
14180 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
14190 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
141a0 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
141b0 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
141c0 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
141d0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
141e0 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
141f0 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
14200 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
14210 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
14220 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
14230 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
14240 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
14250 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
14260 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
14270 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
14280 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
14290 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
142a0 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
142b0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
142c0 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
142d0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
142e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
142f0 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
14300 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
14310 3e 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  >^(This option t
14320 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14330 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
14340 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  nt. If non-zero,
14350 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e   then.** URI han
14360 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
14370 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68  y enabled. If th
14380 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a  e parameter is z
14390 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
143a0 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f  ndling.** is glo
143b0 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29  bally disabled.)
143c0 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69  ^ ^If URI handli
143d0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
143e0 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
143f0 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20  names.** passed 
14400 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
14410 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
14420 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  en_v2()], [sqlit
14430 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
14440 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
14450 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
14460 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
14470 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
14480 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
14490 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
144a0 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
144b0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
144c0 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
144d0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
144e0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
144f0 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c  ^If it is global
14500 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
14510 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
14520 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
14530 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
14540 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
14550 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
14560 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
14570 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
14580 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c  ned. ^(By defaul
14590 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
145a0 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
145b0 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
145c0 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
145d0 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
145e0 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
145f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
14600 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
14610 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ed.)^.**.** [[SQ
14620 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
14630 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
14640 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14650 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
14660 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e  EX_SCAN.** <dd>^
14670 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
14680 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67  s a single integ
14690 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  er argument whic
146a0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
146b0 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e   as.** a boolean
146c0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61   in order to ena
146d0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
146e0 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
146f0 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a  ng indices for.*
14700 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  * full table sca
14710 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
14720 6f 70 74 69 6d 69 7a 65 72 2e 20 20 5e 54 68 65  optimizer.  ^The
14730 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
14740 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a   is determined.*
14750 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  * by the [SQLITE
14760 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f  _ALLOW_COVERING_
14770 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70  INDEX_SCAN] comp
14780 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
14790 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69   or is "on".** i
147a0 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74  f that compile-t
147b0 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d  ime option is om
147c0 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62  itted..** The ab
147d0 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65  ility to disable
147e0 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
147f0 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
14800 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
14810 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20  s.** is because 
14820 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79  some incorrectly
14830 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70   coded legacy ap
14840 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74  plications might
14850 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20   malfunction.** 
14860 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a  when the optimiz
14870 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
14880 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65  .  Providing the
14890 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64   ability to.** d
148a0 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d  isable the optim
148b0 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74  ization allows t
148c0 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20  he older, buggy 
148d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
148e0 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68   to work.** with
148f0 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20  out change even 
14900 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69  with newer versi
14910 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
14920 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14930 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b  NFIG_PCACHE]] [[
14940 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14950 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74  TPCACHE]].** <dt
14960 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
14970 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45  CACHE and SQLITE
14980 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14990 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20  E.** <dd> These 
149a0 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f  options are obso
149b0 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20  lete and should 
149c0 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e  not be used by n
149d0 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79  ew code..** They
149e0 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f   are retained fo
149f0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
14a00 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72  atibility but ar
14a10 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a  e now no-ops..**
14a20 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14a30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
14a40 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  LOG]].** <dt>SQL
14a50 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
14a60 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  G.** <dd>This op
14a70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
14a80 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65  ilable if sqlite
14a90 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
14aa0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
14ab0 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20  _ENABLE_SQLLOG] 
14ac0 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61  pre-processor ma
14ad0 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65  cro defined. The
14ae0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
14af0 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70  should.** be a p
14b00 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63  ointer to a func
14b10 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69  tion of type voi
14b20 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
14b30 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  e3*,const char*,
14b40 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65   int)..** The se
14b50 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f  cond should be o
14b60 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20  f type (void*). 
14b70 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  The callback is 
14b80 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c  invoked by the l
14b90 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72  ibrary.** in thr
14ba0 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63  ee separate circ
14bb0 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74  umstances, ident
14bc0 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c  ified by the val
14bd0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
14be0 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
14bf0 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75  eter. If the fou
14c00 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
14c10 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74   0, then the dat
14c20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14c30 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  .** passed as th
14c40 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
14c50 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  t has just been 
14c60 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72  opened. The thir
14c70 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f  d argument.** po
14c80 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72  ints to a buffer
14c90 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
14ca0 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e  name of the main
14cb0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20   database file. 
14cc0 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  If the.** fourth
14cd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c   parameter is 1,
14ce0 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   then the SQL st
14cf0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65  atement that the
14d00 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
14d10 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61  .** points to ha
14d20 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63  s just been exec
14d30 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65  uted. Or, if the
14d40 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
14d50 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20  r is 2, then.** 
14d60 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  the connection b
14d70 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74  eing passed as t
14d80 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
14d90 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f  ter is being clo
14da0 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72  sed. The.** thir
14db0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  d parameter is p
14dc0 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68  assed NULL In th
14dd0 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61  is case.  An exa
14de0 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68  mple of using th
14df0 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  is.** configurat
14e00 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  ion option can b
14e10 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74  e seen in the "t
14e20 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f  est_sqllog.c" so
14e30 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20  urce file in.** 
14e40 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51  the canonical SQ
14e50 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65  Lite source tree
14e60 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
14e80 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  P_SIZE]].** <dt>
14e90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
14ea0 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e  AP_SIZE.** <dd>^
14eb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
14ec0 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77  AP_SIZE takes tw
14ed0 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  o 64-bit integer
14ee0 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29   (sqlite3_int64)
14ef0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
14f00 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20  are the default 
14f10 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20  mmap size limit 
14f20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  (the default set
14f30 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41  ting for.** [PRA
14f40 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20  GMA mmap_size]) 
14f50 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
14f60 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
14f70 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65  e limit..** ^The
14f80 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
14f90 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
14fa0 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62  en by each datab
14fb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75  ase connection u
14fc0 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74  sing.** either t
14fd0 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  he [PRAGMA mmap_
14fe0 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f  size] command, o
14ff0 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a  r by using the.*
15000 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
15010 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
15020 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20  control.  ^(The 
15030 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
15040 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 63 61 6e  mmap size.** can
15050 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 61  not be changed a
15060 74 20 72 75 6e 2d 74 69 6d 65 2e 20 20 4e 6f 72  t run-time.  Nor
15070 20 6d 61 79 20 74 68 65 20 6d 61 78 69 6d 75 6d   may the maximum
15080 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
15090 7a 65 0a 2a 2a 20 65 78 63 65 65 64 20 74 68 65  ze.** exceed the
150a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61   compile-time ma
150b0 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20  ximum mmap size 
150c0 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  set by the.** [S
150d0 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53  QLITE_MAX_MMAP_S
150e0 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  IZE] compile-tim
150f0 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e  e option.)^.** ^
15100 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65  If either argume
15110 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  nt to this optio
15120 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  n is negative, t
15130 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e  hen that argumen
15140 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20  t is.** changed 
15150 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74  to its compile-t
15160 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a  ime default..**.
15170 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15180 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
15190 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
151a0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
151b0 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e  EAPSIZE.** <dd>^
151c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
151d0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
151e0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
151f0 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 0a  led for Windows.
15200 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
15210 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43  ITE_WIN32_MALLOC
15220 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
15230 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 0a 2a  macro defined..*
15240 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
15250 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74  WIN32_HEAPSIZE t
15260 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e  akes a 32-bit un
15270 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76  signed integer v
15280 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65  alue.** that spe
15290 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d  cifies the maxim
152a0 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63  um size of the c
152b0 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 20  reated heap..** 
152c0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
152d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
152e0 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
152f0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
15300 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15310 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
15320 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
15330 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15340 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
15350 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
15360 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15370 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
15380 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
15390 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
153a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
153b0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
153c0 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
153d0 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
153e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
153f0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
15400 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
15410 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
15420 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15430 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
15440 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
15450 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
15460 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15470 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
15480 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
15490 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
154a0 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
154b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
154c0 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
154d0 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
154e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
154f0 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
15500 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
15510 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
15520 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15530 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
15540 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
15550 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
15560 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
15570 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
15580 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
15590 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
155a0 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
155b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
155c0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
155d0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
155e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
155f0 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
15600 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20     14  /* no-op 
15610 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15620 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
15630 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d  HE    15  /* no-
15640 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
15650 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
15660 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
15670 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
15680 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15690 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
156a0 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
156b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
156c0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20  CONFIG_PCACHE2  
156d0 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74      18  /* sqlit
156e0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
156f0 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
15700 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15710 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a  PCACHE2   19  /*
15720 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
15730 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
15740 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15750 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
15760 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e  X_SCAN 20  /* in
15770 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
15780 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
15790 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78  G       21  /* x
157a0 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f  Sqllog, void* */
157b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
157c0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
157d0 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74      22  /* sqlit
157e0 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65  e3_int64, sqlite
157f0 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69  3_int64 */.#defi
15800 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15810 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
15820 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20       23  /* int 
15830 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nByte */../*.** 
15840 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
15850 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f  se Connection Co
15860 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
15870 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
15880 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
15890 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
158a0 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
158b0 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
158c0 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
158d0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
158e0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
158f0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
15900 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
15910 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
15920 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
15930 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
15940 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
15950 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
15960 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
15970 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
15980 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
15990 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
159a0 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
159b0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
159c0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
159d0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
159e0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
159f0 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
15a00 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
15a10 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
15a20 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
15a30 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
15a40 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
15a50 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
15a60 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
15a70 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
15a80 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
15a90 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
15aa0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
15ab0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
15ac0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
15ad0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
15ae0 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
15af0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
15b00 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
15b10 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
15b20 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
15b30 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
15b40 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
15b50 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
15b60 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15b70 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
15b80 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
15b90 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
15ba0 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
15bb0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66   to a memory buf
15bc0 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
15bd0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
15be0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
15bf0 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
15c00 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
15c10 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
15c20 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
15c30 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
15c40 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
15c50 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
15c60 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
15c70 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
15c80 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
15c90 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15ca0 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
15cb0 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
15cc0 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
15cd0 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
15ce0 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
15cf0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
15d00 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
15d10 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
15d20 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
15d30 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
15d40 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
15d50 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
15d60 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
15d70 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
15d80 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
15d90 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
15da0 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
15db0 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
15dc0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
15dd0 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
15de0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
15df0 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
15e00 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
15e10 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
15e20 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
15e30 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74  ext smaller mult
15e40 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68  iple of 8.  ^(Th
15e50 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
15e60 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  ry.** configurat
15e70 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61  ion for a databa
15e80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61  se connection ca
15e90 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65  n only be change
15ea0 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63  d when that.** c
15eb0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74  onnection is not
15ec0 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
15ed0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
15ee0 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77  y, or in other w
15ef0 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65  ords.** when the
15f00 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22   "current value"
15f10 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
15f20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74  [sqlite3_db_stat
15f30 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f  us](D,[SQLITE_CO
15f40 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
15f50 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  ...) is zero..**
15f60 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
15f70 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
15f80 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66  side memory conf
15f90 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c  iguration when l
15fa0 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f  ookaside.** memo
15fb0 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61  ry is in use lea
15fc0 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72  ves the configur
15fd0 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20  ation unchanged 
15fe0 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  and returns .** 
15ff0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e  [SQLITE_BUSY].)^
16000 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
16010 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16020 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e  ENABLE_FKEY</dt>
16030 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
16040 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
16050 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
16060 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65  le the enforceme
16070 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67  nt of.** [foreig
16080 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74  n key constraint
16090 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c  s].  There shoul
160a0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
160b0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
160c0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
160d0 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
160e0 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
160f0 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f   disable FK enfo
16100 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69  rcement,.** posi
16110 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46  tive to enable F
16120 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72  K enforcement or
16130 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
16140 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  ve FK enforcemen
16150 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20  t.** unchanged. 
16160 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
16170 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
16180 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
16190 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
161a0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
161b0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
161c0 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d  ther FK enforcem
161d0 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e  ent is off or on
161e0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
161f0 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
16200 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
16210 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
16220 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
16230 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e  h case the FK en
16240 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e  forcement settin
16250 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
16260 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
16270 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
16280 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
16290 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  RIGGER</dt>.** <
162a0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
162b0 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
162c0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43  le or disable [C
162d0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
162e0 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68  triggers]..** Th
162f0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
16300 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
16310 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
16320 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
16330 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
16340 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
16350 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70  e triggers,.** p
16360 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
16370 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65  e triggers or ne
16380 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
16390 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68  the setting unch
163a0 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
163b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
163c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
163d0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
163e0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
163f0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
16400 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72  icate whether tr
16410 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62  iggers are disab
16420 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
16430 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
16440 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
16450 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
16460 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
16470 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
16480 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72  case the trigger
16490 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
164a0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
164b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
164c0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
164d0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
164e0 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31  ASIDE       1001
164f0 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
16500 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
16510 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
16520 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30  ABLE_FKEY     10
16530 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  02  /* int int* 
16540 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16550 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
16560 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20  E_TRIGGER  1003 
16570 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
16580 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16590 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
165a0 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
165b0 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ult Codes.**.** 
165c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
165d0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
165e0 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
165f0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
16600 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
16610 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
16620 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
16630 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64  e. ^The extended
16640 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
16650 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
16660 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73   default for his
16670 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
16680 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ility..*/.SQLITE
16690 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
166a0 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
166b0 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
166c0 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
166d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
166e0 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
166f0 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
16700 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65  y in most SQLite
16710 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20   tables (except 
16720 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  for [WITHOUT ROW
16730 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68  ID] tables).** h
16740 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
16750 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
16760 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
16770 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
16780 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
16790 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
167a0 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
167b0 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
167c0 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
167d0 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
167e0 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
167f0 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
16800 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
16810 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
16820 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
16830 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
16840 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
16850 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
16860 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
16870 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
16880 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
16890 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
168a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73  ^The sqlite3_las
168b0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
168c0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
168d0 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
168e0 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20  of the .** most 
168f0 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
16900 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20  l [INSERT] into 
16910 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72  a rowid table or
16920 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
16930 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20  .** on database 
16940 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a  connection D..**
16950 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b   ^Inserts into [
16960 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
16970 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65  ables are not re
16980 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e  corded..** ^If n
16990 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
169a0 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69  SERT]s into rowi
169b0 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65  d tables.** have
169c0 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
169d0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
169e0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a  onnection D, .**
169f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61   then sqlite3_la
16a00 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
16a10 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  D) returns zero.
16a20 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
16a30 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
16a40 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
16a50 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
16a60 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
16a70 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
16a80 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
16a90 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
16aa0 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
16ab0 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
16ac0 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
16ad0 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
16ae0 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
16af0 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
16b00 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
16b10 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
16b20 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
16b30 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
16b40 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
16b50 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
16b60 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
16b70 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
16b80 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
16b90 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
16ba0 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
16bb0 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
16bc0 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
16bd0 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
16be0 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
16bf0 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
16c00 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
16c10 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
16c20 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
16c30 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
16c40 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
16c50 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
16c60 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
16c70 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
16c80 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
16c90 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
16ca0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
16cb0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
16cc0 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
16cd0 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
16ce0 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
16cf0 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
16d00 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
16d10 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
16d20 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
16d30 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
16d40 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
16d50 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
16d60 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
16d70 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
16d80 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
16d90 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
16da0 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
16db0 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
16dc0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
16dd0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
16de0 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
16df0 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
16e00 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
16e10 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
16e20 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
16e30 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
16e40 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
16e50 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
16e60 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
16e70 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
16e80 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
16e90 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
16ea0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
16eb0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
16ec0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
16ed0 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
16ee0 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
16ef0 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
16f00 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
16f10 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
16f20 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
16f30 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
16f40 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
16f50 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
16f60 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
16f70 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
16f80 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
16f90 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
16fa0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
16fb0 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
16fc0 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
16fd0 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
16fe0 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
16ff0 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
17000 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
17010 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  owid]..*/.SQLITE
17020 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
17030 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
17040 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
17050 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
17060 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
17070 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
17080 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
17090 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
170a0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
170b0 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72  er of database r
170c0 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68  ows that were ch
170d0 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65  anged.** or inse
170e0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20  rted or deleted 
170f0 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
17100 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53  ntly completed S
17110 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
17120 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
17130 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
17140 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  cified by the fi
17150 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
17160 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73  * ^(Only changes
17170 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74   that are direct
17180 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ly specified by 
17190 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  the [INSERT], [U
171a0 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44  PDATE],.** or [D
171b0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
171c0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41   are counted.  A
171d0 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
171e0 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72   caused by.** tr
171f0 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69  iggers or [forei
17200 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
17210 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
17220 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73  )^ Use the.** [s
17230 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
17240 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
17250 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74   to find the tot
17260 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  al number of cha
17270 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e  nges.** includin
17280 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  g changes caused
17290 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64   by triggers and
172a0 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74   foreign key act
172b0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61  ions..**.** ^Cha
172c0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
172d0 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65  hat are simulate
172e0 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44  d by an [INSTEAD
172f0 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20   OF trigger].** 
17300 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
17310 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c    Only real tabl
17320 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  e changes are co
17330 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  unted..**.** ^(A
17340 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73   "row change" is
17350 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73   a change to a s
17360 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73  ingle row of a s
17370 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63  ingle table.** c
17380 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45  aused by an INSE
17390 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55  RT, DELETE, or U
173a0 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e  PDATE statement.
173b0 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61    Rows that.** a
173c0 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69  re changed as si
173d0 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52  de effects of [R
173e0 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
173f0 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a  nt resolution,.*
17400 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52  * rollback, ABOR
17410 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44  T processing, [D
17420 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62  ROP TABLE], or b
17430 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d  y any other.** m
17440 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74  echanisms do not
17450 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74   count as direct
17460 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a   row changes.)^.
17470 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72  **.** A "trigger
17480 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73   context" is a s
17490 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f  cope of executio
174a0 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e  n that begins an
174b0 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74  d.** ends with t
174c0 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b  he script of a [
174d0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
174e0 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d   trigger]. .** M
174f0 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
17500 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
17510 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
17520 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
17530 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
17540 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
17550 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
17560 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
17570 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
17580 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
17590 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
175a0 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
175b0 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
175c0 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
175d0 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
175e0 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
175f0 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
17600 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
17610 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
17620 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
17630 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
17640 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72  y does.** not cr
17650 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67  eate a new trigg
17660 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
17670 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
17680 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
17690 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f  ber of direct ro
176a0 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  w changes in the
176b0 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
176c0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
176d0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
176e0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
176f0 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  ame.** trigger c
17700 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
17710 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64  hus, when called
17720 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
17730 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69  vel, this functi
17740 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  on returns the.*
17750 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  * number of chan
17760 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
17770 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
17780 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
17790 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63  .** that also oc
177a0 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f  curred at the to
177b0 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68  p level.  ^(With
177c0 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
177d0 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65   trigger,.** the
177e0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
177f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
17800 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69   be called to fi
17810 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
17820 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
17830 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
17840 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
17850 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
17860 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
17870 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
17880 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72  y of the same tr
17890 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65  igger..** Howeve
178a0 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65  r, the number re
178b0 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
178c0 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a  include changes.
178d0 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62  ** caused by sub
178e0 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74  triggers since t
178f0 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20  hose have their 
17900 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a  own context.)^.*
17910 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
17920 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
17930 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
17940 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
17950 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
17960 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63  gma], and the [c
17970 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
17980 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
17990 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
179a0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
179b0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
179c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
179d0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
179e0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
179f0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
17a00 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
17a10 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
17a20 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
17a30 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  ningful..*/.SQLI
17a40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
17a50 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
17a60 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
17a70 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
17a80 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
17a90 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
17aa0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
17ab0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
17ac0 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
17ad0 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a  ed by [INSERT],.
17ae0 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b  ** [UPDATE] or [
17af0 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
17b00 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61  ts since the [da
17b10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17b20 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a  n] was opened..*
17b30 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65  * ^(The count re
17b40 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
17b50 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
17b60 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63  ) includes all c
17b70 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61  hanges.** from a
17b80 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  ll [CREATE TRIGG
17b90 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f  ER | trigger] co
17ba0 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67  ntexts and chang
17bb0 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66  es made by.** [f
17bc0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
17bd0 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ns]. However,.**
17be0 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20   the count does 
17bf0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
17c00 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ges used to impl
17c10 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20  ement [REPLACE] 
17c20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20  constraints,.** 
17c30 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20  do rollbacks or 
17c40 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
17c50 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45  , or [DROP TABLE
17c60 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54  ] processing.  T
17c70 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73  he.** count does
17c80 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77   not include row
17c90 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20  s of views that 
17ca0 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44  fire an [INSTEAD
17cb0 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a   OF trigger],.**
17cc0 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49   though if the I
17cd0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
17ce0 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  r makes changes 
17cf0 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73  of its own, thos
17d00 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72  e changes .** ar
17d10 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20  e counted.)^.** 
17d20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74  ^The sqlite3_tot
17d30 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  al_changes() fun
17d40 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65  ction counts the
17d50 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e   changes as soon
17d60 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   as.** the state
17d70 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
17d80 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65  them is complete
17d90 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74  d (when the stat
17da0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20  ement handle.** 
17db0 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
17dc0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
17dd0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
17de0 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  ize()])..**.** S
17df0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
17e00 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
17e10 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
17e20 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
17e30 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
17e40 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
17e50 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
17e60 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
17e70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
17e80 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
17e90 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
17ea0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
17eb0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
17ec0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
17ed0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
17ee0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
17ef0 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
17f00 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
17f10 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  ningful..*/.SQLI
17f20 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
17f30 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
17f40 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
17f50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
17f60 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
17f70 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a  nning Query.**.*
17f80 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
17f90 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
17fa0 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
17fb0 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
17fc0 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
17fd0 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
17fe0 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
17ff0 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
18000 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
18010 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
18020 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
18030 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
18040 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
18050 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
18060 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
18070 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
18080 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
18090 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
180a0 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
180b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
180c0 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
180d0 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
180e0 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
180f0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
18100 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
18110 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
18120 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
18130 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
18140 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
18150 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18160 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
18170 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
18180 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
18190 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
181a0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
181b0 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
181c0 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
181d0 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
181e0 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
181f0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18200 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
18210 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
18220 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
18230 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
18240 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
18250 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
18260 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
18270 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
18280 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
18290 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
182a0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
182b0 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
182c0 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
182d0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
182e0 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
182f0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
18300 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
18310 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
18320 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
18330 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
18340 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
18350 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
18360 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
18370 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
18380 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
18390 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
183a0 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
183b0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
183c0 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
183d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
183e0 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
183f0 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
18400 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
18410 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
18420 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
18430 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
18440 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
18450 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
18460 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
18470 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
18480 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
18490 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
184a0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
184b0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
184c0 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
184d0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
184e0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
184f0 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
18500 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
18510 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
18520 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
18530 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
18540 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
18550 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
18560 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18570 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
18580 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
18590 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
185a0 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
185b0 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
185c0 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
185d0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
185e0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
185f0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
18600 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
18610 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
18620 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
18630 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
18640 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
18650 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
18660 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
18670 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
18680 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
18690 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
186a0 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
186b0 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
186c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
186d0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
186e0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
186f0 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
18700 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
18710 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
18720 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
18730 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
18740 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
18750 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
18760 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
18770 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
18780 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
18790 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
187a0 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
187b0 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
187c0 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
187d0 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
187e0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
187f0 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
18800 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
18810 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
18820 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
18830 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
18840 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
18850 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
18860 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
18870 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
18880 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
18890 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
188a0 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
188b0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
188c0 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
188d0 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
188e0 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
188f0 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
18900 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
18910 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
18920 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
18930 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
18940 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
18950 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
18960 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
18970 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
18980 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
18990 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
189a0 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
189b0 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
189c0 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
189d0 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
189e0 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
189f0 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
18a00 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
18a10 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
18a20 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
18a30 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
18a40 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
18a50 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
18a60 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
18a70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
18a80 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
18a90 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
18aa0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
18ab0 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
18ac0 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
18ad0 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
18ae0 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
18af0 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
18b00 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
18b10 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
18b20 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
18b30 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
18b40 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
18b50 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
18b60 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
18b70 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
18b80 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
18b90 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
18ba0 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
18bb0 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
18bc0 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
18bd0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
18be0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
18bf0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
18c00 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
18c10 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
18c20 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
18c30 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
18c40 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
18c50 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
18c60 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
18c70 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
18c80 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
18c90 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
18ca0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
18cb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
18cc0 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
18cd0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
18ce0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
18cf0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
18d00 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49  e order..*/.SQLI
18d10 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
18d20 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
18d30 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51  t char *sql);.SQ
18d40 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
18d50 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
18d60 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
18d70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18d80 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
18d90 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
18da0 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
18db0 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ors.**.** ^This 
18dc0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
18dd0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
18de0 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
18df0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a  nvoked whenever.
18e00 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
18e10 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20   made to open a 
18e20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74  database table t
18e30 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hat another thre
18e40 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
18e50 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a   has locked..**.
18e60 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
18e70 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
18e80 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
18e90 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
18ea0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
18eb0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
18ec0 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
18ed0 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
18ee0 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
18ef0 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
18f00 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
18f10 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
18f20 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
18f30 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
18f40 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
18f50 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
18f60 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
18f70 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
18f80 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
18f90 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
18fa0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
18fb0 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
18fc0 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
18fd0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
18fe0 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
18ff0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
19000 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
19010 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
19020 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
19030 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
19040 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69  d for this locki
19050 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
19060 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
19070 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
19080 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
19090 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
190a0 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
190b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
190c0 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
190d0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
190e0 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
190f0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  urned..** ^If th
19100 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
19110 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
19120 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
19130 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
19140 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
19150 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
19160 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
19170 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
19180 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
19190 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
191a0 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
191b0 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
191c0 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
191d0 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
191e0 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
191f0 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
19200 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
19210 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
19220 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
19230 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
19240 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
19250 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
19260 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  USY].** or [SQLI
19270 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
19280 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  ] instead of inv
19290 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68  oking the busy h
192a0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
192b0 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
192c0 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
192d0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
192e0 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
192f0 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
19300 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
19310 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
19320 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
19330 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
19340 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
19350 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
19360 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
19370 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
19380 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
19390 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
193a0 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
193b0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
193c0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
193d0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
193e0 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
193f0 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
19400 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
19410 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
19420 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
19430 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
19440 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
19450 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
19460 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
19470 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
19480 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
19490 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
194a0 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
194b0 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
194c0 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
194d0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
194e0 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
194f0 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
19500 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
19510 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
19520 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
19530 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
19540 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
19550 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
19560 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
19570 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
19580 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
19590 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
195a0 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
195b0 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
195c0 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
195d0 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
195e0 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
195f0 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
19600 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
19610 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
19620 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
19630 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
19640 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
19650 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
19660 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
19670 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
19680 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
19690 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
196a0 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
196b0 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
196c0 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
196d0 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
196e0 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61  .  ^If it is una
196f0 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
19700 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
19710 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
19720 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
19730 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
19740 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
19750 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
19760 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
19770 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
19780 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
19790 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
197a0 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
197b0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
197c0 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72  CKED].  ^This er
197d0 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69  ror code promoti
197e0 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20  on.** forces an 
197f0 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61  automatic rollba
19800 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65  ck of the change
19810 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c  s.  See the.** <
19820 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63  a href="/cvstrac
19830 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69  /wiki?p=Corrupti
19840 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
19850 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70  rror">.** Corrup
19860 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
19870 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20  yError</a> wiki 
19880 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75  page for a discu
19890 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20  ssion of why.** 
198a0 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e  this is importan
198b0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  t..**.** ^(There
198c0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
198d0 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
198e0 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
198f0 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
19900 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
19910 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
19920 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
19930 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
19940 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
19950 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
19960 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
19970 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
19980 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  * will also set 
19990 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73  or clear the bus
199a0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
199b0 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
199c0 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
199d0 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
199e0 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
199f0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
19a00 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
19a10 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
19a20 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20  dler.  Any such 
19a30 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
19a40 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
19a50 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
19a60 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
19a70 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
19a80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
19a90 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
19aa0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
19ab0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
19ac0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
19ad0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
19ae0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
19af0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
19b00 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
19b10 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
19b20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
19b30 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
19b40 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
19b50 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
19b60 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
19b70 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
19b80 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
19b90 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
19ba0 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
19bb0 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
19bc0 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
19bd0 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
19be0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
19bf0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
19c00 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
19c10 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
19c20 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
19c30 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
19c40 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
19c50 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
19c60 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
19c70 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
19c80 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
19c90 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
19ca0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
19cb0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
19cc0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
19cd0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
19ce0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
19cf0 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
19d00 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
19d10 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
19d20 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
19d30 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
19d40 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
19d50 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
19d60 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
19d70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
19d80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19d90 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e  n] any any given
19da0 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
19db0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
19dc0 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
19dd0 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
19de0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
19df0 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
19e00 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
19e10 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
19e20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
19e30 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51  cleared.)^.*/.SQ
19e40 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
19e50 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
19e60 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
19e70 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
19e80 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
19e90 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
19ea0 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
19eb0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
19ec0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
19ed0 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
19ee0 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
19ef0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
19f00 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
19f10 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
19f20 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
19f30 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
19f40 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
19f50 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
19f60 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
19f70 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
19f80 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
19f90 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
19fa0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
19fb0 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
19fc0 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
19fd0 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
19fe0 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
19ff0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
1a000 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
1a010 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
1a020 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
1a030 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
1a040 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
1a050 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
1a060 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
1a070 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
1a080 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
1a090 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
1a0a0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1a0b0 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
1a0c0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1a0d0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
1a0e0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1a0f0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
1a100 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
1a110 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1a120 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
1a130 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
1a140 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
1a150 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
1a160 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
1a170 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
1a180 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1a190 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
1a1a0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
1a1b0 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
1a1c0 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
1a1d0 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
1a1e0 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
1a1f0 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
1a200 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
1a210 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
1a220 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
1a230 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
1a240 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1a250 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
1a260 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
1a270 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1a280 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
1a290 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
1a2a0 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
1a2b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
1a2c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
1a2d0 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
1a2e0 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
1a2f0 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
1a300 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
1a310 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
1a320 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
1a330 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
1a340 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
1a350 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
1a360 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
1a370 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
1a380 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
1a390 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
1a3a0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
1a3b0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1a3c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1a3d0 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
1a3e0 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
1a3f0 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
1a400 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
1a410 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
1a420 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
1a430 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
1a440 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
1a450 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
1a460 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1a470 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
1a480 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
1a490 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
1a4a0 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
1a4b0 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
1a4c0 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
1a4d0 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
1a4e0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1a4f0 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
1a500 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
1a510 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
1a520 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
1a530 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
1a540 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1a550 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1a560 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
1a570 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
1a580 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1a590 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
1a5a0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1a5b0 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
1a5c0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1a5d0 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
1a5e0 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
1a5f0 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
1a600 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
1a610 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
1a620 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
1a630 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a640 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
1a650 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a660 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
1a670 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1a680 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
1a690 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1a6a0 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
1a6b0 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
1a6c0 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
1a6d0 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
1a6e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
1a6f0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1a700 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
1a710 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
1a720 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
1a730 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
1a740 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
1a750 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
1a760 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
1a770 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
1a780 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
1a790 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1a7a0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
1a7b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a7c0 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
1a7d0 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
1a7e0 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
1a7f0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1a800 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
1a810 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
1a820 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
1a830 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
1a840 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
1a850 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
1a860 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
1a870 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
1a880 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
1a890 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
1a8a0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
1a8b0 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
1a8c0 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
1a8d0 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
1a8e0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1a8f0 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
1a900 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1a910 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
1a920 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
1a930 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1a940 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
1a950 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
1a960 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
1a970 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
1a980 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
1a990 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1a9a0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
1a9b0 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
1a9c0 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
1a9d0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
1a9e0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
1a9f0 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
1aa00 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
1aa10 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
1aa20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
1aa30 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
1aa40 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
1aa50 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
1aa60 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
1aa70 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
1aa80 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
1aa90 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
1aaa0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
1aab0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1aac0 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
1aad0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1aae0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1aaf0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  PI int sqlite3_g
1ab00 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
1ab10 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1ab20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
1ab30 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
1ab40 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1ab50 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
1ab60 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
1ab70 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
1ab80 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
1ab90 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
1aba0 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
1abb0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1abc0 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
1abd0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1abe0 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
1abf0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1ac00 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
1ac10 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
1ac20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
1ac30 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
1ac40 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
1ac50 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  here */.);.SQLIT
1ac60 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1ac70 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
1ac80 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
1ac90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
1aca0 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
1acb0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
1acc0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1acd0 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
1ace0 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
1acf0 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
1ad00 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
1ad10 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
1ad20 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
1ad30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ad40 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
1ad50 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1ad60 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
1ad70 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
1ad80 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
1ad90 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
1ada0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
1adb0 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
1adc0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1add0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
1ade0 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
1adf0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
1ae00 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
1ae10 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1ae20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1ae30 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
1ae40 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
1ae50 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
1ae60 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
1ae70 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
1ae80 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
1ae90 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1aea0 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
1aeb0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
1aec0 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
1aed0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
1aee0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
1aef0 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
1af00 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
1af10 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
1af20 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1af30 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
1af40 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
1af50 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
1af60 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
1af70 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
1af80 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
1af90 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
1afa0 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
1afb0 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
1afc0 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
1afd0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
1afe0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
1aff0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
1b000 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
1b010 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
1b020 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
1b030 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
1b040 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
1b050 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
1b060 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
1b070 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
1b080 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
1b090 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
1b0a0 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
1b0b0 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
1b0c0 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
1b0d0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
1b0e0 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
1b0f0 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
1b100 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
1b110 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
1b120 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
1b130 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
1b140 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
1b150 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
1b160 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
1b170 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
1b180 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
1b190 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
1b1a0 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
1b1b0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1b1c0 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
1b1d0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
1b1e0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
1b1f0 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
1b200 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
1b210 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
1b220 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
1b230 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
1b240 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
1b250 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1b260 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
1b270 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
1b280 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
1b290 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
1b2a0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
1b2b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1b2c0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
1b2d0 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
1b2e0 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
1b2f0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1b300 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
1b310 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
1b320 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
1b330 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
1b340 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
1b350 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
1b360 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
1b370 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1b380 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
1b390 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
1b3a0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
1b3b0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
1b3c0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
1b3d0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
1b3e0 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
1b3f0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
1b400 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1b410 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
1b420 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
1b430 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
1b440 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
1b450 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
1b460 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
1b470 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
1b480 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
1b490 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
1b4a0 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
1b4b0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
1b4c0 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
1b4d0 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
1b4e0 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
1b4f0 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
1b500 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
1b510 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
1b520 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
1b530 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
1b540 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
1b550 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
1b560 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
1b570 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1b580 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1b590 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
1b5a0 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
1b5b0 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
1b5c0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1b5d0 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
1b5e0 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
1b5f0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1b600 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1b610 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1b620 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1b630 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1b640 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1b650 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1b660 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
1b670 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1b680 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1b690 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1b6a0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1b6b0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1b6c0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
1b6d0 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
1b6e0 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
1b6f0 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
1b700 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
1b710 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
1b720 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
1b730 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1b740 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1b750 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1b760 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1b770 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
1b780 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
1b790 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1b7a0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
1b7b0 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
1b7c0 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
1b7d0 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
1b7e0 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
1b7f0 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
1b800 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1b810 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1b820 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1b830 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1b840 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
1b850 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
1b860 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1b870 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
1b880 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
1b890 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
1b8a0 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
1b8b0 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
1b8c0 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
1b8d0 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
1b8e0 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
1b8f0 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
1b900 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
1b910 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
1b920 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
1b930 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
1b940 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
1b950 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
1b960 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
1b970 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
1b980 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
1b990 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
1b9a0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
1b9b0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1b9c0 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
1b9d0 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
1b9e0 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
1b9f0 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
1ba00 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
1ba10 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
1ba20 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1ba30 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1ba40 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1ba50 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1ba60 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1ba70 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
1ba80 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1ba90 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1baa0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1bab0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1bac0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1bad0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1bae0 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
1baf0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
1bb00 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1bb10 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
1bb20 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
1bb30 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
1bb40 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
1bb50 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
1bb60 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
1bb70 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
1bb80 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
1bb90 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
1bba0 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
1bbb0 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
1bbc0 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
1bbd0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
1bbe0 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
1bbf0 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
1bc00 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
1bc10 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  ing.)^.*/.SQLITE
1bc20 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1bc30 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
1bc40 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c   char*,...);.SQL
1bc50 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
1bc60 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
1bc70 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1bc80 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ist);.SQLITE_API
1bc90 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1bca0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1bcb0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1bcc0 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
1bcd0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1bce0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1bcf0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1bd00 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1bd10 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1bd20 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1bd30 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1bd40 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1bd50 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1bd60 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1bd70 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1bd80 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1bd90 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1bda0 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1bdb0 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1bdc0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1bdd0 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1bde0 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1bdf0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1be00 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1be10 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1be20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1be30 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1be40 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1be50 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1be60 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1be70 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1be80 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1be90 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1bea0 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1beb0 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1bec0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1bed0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1bee0 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1bef0 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1bf00 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1bf10 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1bf20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1bf30 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1bf40 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1bf50 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1bf60 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1bf70 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1bf80 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1bf90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1bfa0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1bfb0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1bfc0 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1bfd0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1bfe0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1bff0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1c000 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1c010 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1c020 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1c030 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1c040 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1c050 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1c060 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1c070 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1c080 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1c090 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1c0a0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1c0b0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1c0c0 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1c0d0 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1c0e0 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1c0f0 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1c100 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1c110 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1c120 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1c130 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1c140 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1c150 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1c160 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1c170 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1c180 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1c190 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1c1a0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1c1b0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1c1c0 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1c1d0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1c1e0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1c1f0 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1c200 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1c210 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1c220 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1c230 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1c240 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  ^(The sqlite3_re
1c250 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
1c260 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1c270 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1c280 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1c290 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
1c2a0 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
1c2b0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
1c2c0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
1c2d0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
1c2e0 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
1c2f0 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
1c300 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20  ** parameter.)^ 
1c310 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70  ^ If the first p
1c320 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1c330 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
1c340 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1c350 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
1c360 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
1c370 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
1c380 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1c390 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  ) where N is the
1c3a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1c3b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1c3c0 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74  lloc()..** ^If t
1c3d0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1c3e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1c3f0 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
1c400 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
1c410 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1c420 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
1c430 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
1c440 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
1c450 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
1c460 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1c470 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1c480 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c  alloc()..** ^sql
1c490 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1c4a0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1c4b0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
1c4c0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
1c4d0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1c4e0 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
1c4f0 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
1c500 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
1c510 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20  le..** ^If M is 
1c520 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
1c530 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1c540 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
1c550 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
1c560 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1c570 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
1c580 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1c590 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
1c5a0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1c5b0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
1c5c0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1c5d0 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1c5e0 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1c5f0 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
1c600 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
1c610 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
1c620 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
1c630 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1c640 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1c650 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e  ite3_malloc() an
1c660 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
1c670 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  c().** is always
1c680 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
1c690 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
1c6a0 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61  oundary, or to a
1c6b0 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64  .** 4 byte bound
1c6c0 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49  ary if the [SQLI
1c6d0 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45  TE_4_BYTE_ALIGNE
1c6e0 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c  D_MALLOC] compil
1c6f0 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
1c700 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1c710 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
1c720 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
1c730 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
1c740 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
1c750 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
1c760 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
1c770 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
1c780 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
1c790 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1c7a0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
1c7b0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
1c7c0 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
1c7d0 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
1c7e0 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
1c7f0 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
1c800 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
1c810 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
1c820 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
1c830 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31  te version 3.7.1
1c840 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f  0, the Windows O
1c850 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
1c860 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20  r called.** the 
1c870 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
1c880 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
1c890 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
1c8a0 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
1c8b0 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
1c8c0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
1c8d0 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
1c8e0 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
1c8f0 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
1c900 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
1c910 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
1c920 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
1c930 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
1c940 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64  on errors were d
1c950 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
1c960 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74  they were report
1c970 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
1c980 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
1c990 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
1c9a0 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
1c9b0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
1c9c0 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
1c9d0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
1c9e0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
1c9f0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1ca00 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
1ca10 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
1ca20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
1ca30 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
1ca40 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
1ca50 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1ca60 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
1ca70 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
1ca80 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
1ca90 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
1caa0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
1cab0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
1cac0 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
1cad0 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
1cae0 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
1caf0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
1cb00 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
1cb10 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
1cb20 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
1cb30 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
1cb40 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1cb50 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
1cb60 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  (int);.SQLITE_AP
1cb70 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
1cb80 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
1cb90 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
1cba0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1cbb0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
1cbc0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1cbd0 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
1cbe0 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
1cbf0 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
1cc00 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
1cc10 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
1cc20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
1cc30 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
1cc40 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
1cc50 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
1cc60 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1cc70 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
1cc80 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
1cc90 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
1cca0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
1ccb0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
1ccc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1ccd0 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
1cce0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
1ccf0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
1cd00 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
1cd10 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
1cd20 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
1cd30 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
1cd40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1cd50 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1cd60 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1cd70 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
1cd80 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
1cd90 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1cda0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
1cdb0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
1cdc0 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
1cdd0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
1cde0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1cdf0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
1ce00 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
1ce10 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1ce20 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
1ce30 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
1ce40 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
1ce50 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1ce60 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1ce70 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
1ce80 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
1ce90 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
1cea0 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
1ceb0 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
1cec0 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
1ced0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
1cee0 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
1cef0 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
1cf00 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
1cf10 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
1cf20 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
1cf30 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1cf40 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
1cf50 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1cf60 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
1cf70 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1cf80 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
1cf90 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1cfa0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1cfb0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1cfc0 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
1cfd0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
1cfe0 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
1cff0 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
1d000 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
1d010 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1d020 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ed(void);.SQLITE
1d030 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
1d040 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1d050 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
1d060 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
1d070 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
1d080 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
1d090 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
1d0a0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
1d0b0 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
1d0c0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
1d0d0 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
1d0e0 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
1d0f0 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
1d100 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
1d110 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1d120 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
1d130 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
1d140 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
1d150 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
1d160 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
1d170 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
1d180 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
1d190 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
1d1a0 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
1d1b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
1d1c0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1d1d0 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
1d1e0 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
1d1f0 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
1d200 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
1d210 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
1d220 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1d230 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
1d240 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
1d250 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20  to buffer P..** 
1d260 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68  ^If N is less th
1d270 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20 50 20 63  an one, then P c
1d280 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  an be a NULL poi
1d290 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  nter..**.** ^If 
1d2a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73  this routine has
1d2b0 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f   not been previo
1d2c0 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69  usly called or i
1d2d0 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a  f the previous.*
1d2e0 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73  * call had N les
1d2f0 73 20 74 68 61 6e 20 6f 6e 65 2c 20 74 68 65 6e  s than one, then
1d300 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65   the PRNG is see
1d310 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
1d320 6e 65 73 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64  ness.** obtained
1d330 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
1d340 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  mness method of 
1d350 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1d360 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1d370 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65  ..** ^If the pre
1d380 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
1d390 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61  is routine had a
1d3a0 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65  n N of 1 or more
1d3b0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 70 73 65   then.** the pse
1d3c0 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
1d3d0 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
1d3e0 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
1d3f0 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
1d400 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
1d410 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
1d420 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51  ** method..*/.SQ
1d430 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
1d440 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
1d450 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
1d460 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d470 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
1d480 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
1d490 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
1d4a0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
1d4b0 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69  sters an authori
1d4c0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
1d4d0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
1d4e0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1d4f0 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
1d500 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
1d510 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
1d520 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1d530 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1d540 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
1d550 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
1d560 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
1d570 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1d580 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
1d590 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d5a0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
1d5b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
1d5c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
1d5d0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e  pare16_v2()].  ^
1d5e0 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
1d5f0 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
1d600 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
1d610 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
1d620 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
1d630 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
1d640 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
1d650 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1d660 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1d670 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
1d680 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
1d690 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
1d6a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d6b0 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
1d6c0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1d6d0 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
1d6e0 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
1d6f0 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
1d700 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
1d710 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
1d720 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
1d730 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
1d740 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
1d750 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
1d760 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
1d770 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
1d780 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
1d790 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
1d7a0 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
1d7b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1d7c0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
1d7d0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
1d7e0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
1d7f0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
1d800 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1d810 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
1d820 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d830 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1d840 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1d850 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
1d860 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1d870 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1d880 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
1d890 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
1d8a0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1d8b0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
1d8c0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
1d8d0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
1d8e0 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
1d8f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1d900 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
1d910 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1d920 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1d930 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1d940 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
1d950 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1d960 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1d970 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1d980 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
1d990 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
1d9a0 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
1d9b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1d9c0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
1d9d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1d9e0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
1d9f0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
1da00 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
1da10 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1da20 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
1da30 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1da40 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
1da50 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1da60 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
1da70 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
1da80 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
1da90 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
1daa0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1dab0 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
1dac0 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
1dad0 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
1dae0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1daf0 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
1db00 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1db10 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
1db20 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
1db30 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
1db40 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
1db50 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1db60 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1db70 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
1db80 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1db90 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1dba0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
1dbb0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
1dbc0 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
1dbd0 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
1dbe0 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
1dbf0 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
1dc00 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
1dc10 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
1dc20 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
1dc30 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
1dc40 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
1dc50 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
1dc60 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
1dc70 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
1dc80 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
1dc90 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
1dca0 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
1dcb0 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
1dcc0 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
1dcd0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
1dce0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
1dcf0 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
1dd00 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1dd10 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
1dd20 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
1dd30 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
1dd40 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
1dd50 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
1dd60 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
1dd70 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
1dd80 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
1dd90 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
1dda0 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
1ddb0 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
1ddc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ddd0 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
1dde0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1ddf0 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
1de00 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
1de10 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
1de20 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1de30 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
1de40 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
1de50 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
1de60 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
1de70 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
1de80 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
1de90 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
1dea0 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
1deb0 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
1dec0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
1ded0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
1dee0 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
1def0 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
1df00 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
1df10 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
1df20 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
1df30 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1df40 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
1df50 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
1df60 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
1df70 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
1df80 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
1df90 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
1dfa0 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
1dfb0 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
1dfc0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
1dfd0 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
1dfe0 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
1dff0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
1e000 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
1e010 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
1e020 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
1e030 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
1e040 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
1e050 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
1e060 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
1e070 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
1e080 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
1e090 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
1e0a0 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
1e0b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
1e0c0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
1e0d0 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
1e0e0 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
1e0f0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
1e100 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
1e110 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
1e120 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
1e130 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
1e140 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
1e150 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
1e160 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
1e170 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
1e180 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
1e190 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
1e1a0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
1e1b0 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
1e1c0 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
1e1d0 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
1e1e0 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
1e1f0 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
1e200 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
1e210 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
1e220 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
1e230 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
1e240 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
1e250 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
1e260 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
1e270 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
1e280 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1e290 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1e2a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e2b0 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
1e2c0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1e2d0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1e2e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1e2f0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1e300 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1e310 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1e320 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1e330 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1e340 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
1e350 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1e360 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
1e370 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
1e380 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
1e390 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
1e3a0 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
1e3b0 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
1e3c0 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
1e3d0 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
1e3e0 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
1e3f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
1e400 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
1e410 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
1e420 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e430 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
1e440 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
1e450 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1e460 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
1e470 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
1e480 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1e490 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
1e4a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1e4b0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
1e4c0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
1e4d0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
1e4e0 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
1e4f0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
1e500 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
1e510 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
1e520 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
1e530 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
1e540 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
1e550 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
1e560 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
1e570 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
1e580 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
1e590 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
1e5a0 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51  ma change..*/.SQ
1e5b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1e5c0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1e5d0 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
1e5e0 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
1e5f0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
1e600 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1e610 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1e620 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
1e630 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
1e640 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e650 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
1e660 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
1e670 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
1e680 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1e690 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e6a0 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
1e6b0 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
1e6c0 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
1e6d0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
1e6e0 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
1e6f0 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
1e700 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
1e710 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
1e720 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
1e730 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
1e740 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e750 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1e760 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
1e770 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
1e780 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
1e790 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
1e7a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
1e7b0 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
1e7c0 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
1e7d0 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a   | return code].
1e7e0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  ** from the [sql
1e7f0 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
1e800 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61  flict()] interfa
1e810 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
1e820 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
1e830 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
1e840 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
1e850 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
1e860 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
1e870 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
1e880 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
1e890 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
1e8a0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
1e8b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1e8c0 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
1e8d0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1e8e0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1e8f0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
1e900 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
1e910 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1e920 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
1e930 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
1e940 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
1e950 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
1e960 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
1e970 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1e980 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1e990 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
1e9a0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1e9b0 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
1e9c0 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
1e9d0 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
1e9e0 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
1e9f0 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
1ea00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ea10 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
1ea20 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
1ea30 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
1ea40 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
1ea50 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
1ea60 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
1ea70 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
1ea80 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
1ea90 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
1eaa0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
1eab0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1eac0 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
1ead0 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
1eae0 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
1eaf0 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
1eb00 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
1eb10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
1eb20 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
1eb30 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
1eb40 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1eb50 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
1eb60 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1eb70 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
1eb80 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
1eb90 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
1eba0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
1ebb0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1ebc0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1ebd0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1ebe0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
1ebf0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
1ec00 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
1ec10 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
1ec20 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
1ec30 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
1ec40 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
1ec50 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
1ec60 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
1ec70 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
1ec80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ec90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
1eca0 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
1ecb0 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
1ecc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ecd0 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
1ece0 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
1ecf0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1ed00 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1ed10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ed20 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
1ed30 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
1ed40 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1ed50 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ed60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1ed70 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
1ed80 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
1ed90 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1eda0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1edb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1edc0 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
1edd0 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
1ede0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1edf0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1ee00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ee10 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
1ee20 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
1ee30 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1ee40 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1ee50 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1ee60 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
1ee70 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
1ee80 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1ee90 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1eea0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1eeb0 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
1eec0 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
1eed0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1eee0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1eef0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ef00 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1ef10 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
1ef20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1ef30 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ef40 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
1ef50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
1ef60 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ef70 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ef80 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ef90 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
1efa0 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
1efb0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1efc0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1efd0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1efe0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
1eff0 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
1f000 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f010 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f020 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f030 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1f040 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
1f050 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1f060 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1f070 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f080 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
1f090 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
1f0a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f0b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f0c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f0d0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
1f0e0 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
1f0f0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1f100 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f110 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f120 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
1f130 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
1f140 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1f150 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f160 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f170 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
1f180 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
1f190 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1f1a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f1b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f1c0 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
1f1d0 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
1f1e0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1f1f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f200 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f210 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
1f220 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
1f230 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1f240 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f250 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
1f260 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
1f270 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
1f280 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
1f290 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
1f2a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1f2b0 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
1f2c0 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
1f2d0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
1f2e0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
1f2f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
1f300 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
1f310 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
1f320 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
1f330 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f340 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
1f350 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
1f360 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
1f370 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
1f380 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f390 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
1f3a0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
1f3b0 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
1f3c0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1f3d0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1f3e0 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
1f3f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1f400 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
1f410 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f420 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f430 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
1f440 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
1f450 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
1f460 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
1f470 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f480 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
1f490 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
1f4a0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
1f4b0 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
1f4c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f4d0 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
1f4e0 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
1f4f0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1f500 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f510 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f520 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
1f530 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
1f540 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1f550 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f560 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f570 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
1f580 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
1f590 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f5a0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
1f5b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f5c0 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
1f5d0 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
1f5e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f5f0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
1f600 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f610 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
1f620 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
1f630 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f640 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
1f650 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f660 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
1f670 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
1f680 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
1f690 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
1f6a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f6b0 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
1f6c0 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
1f6d0 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
1f6e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1f6f0 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20  ECURSIVE        
1f700 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c      33   /* NULL
1f710 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
1f720 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a              */..
1f730 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f740 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
1f750 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
1f760 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1f770 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
1f780 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
1f790 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
1f7a0 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
1f7b0 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
1f7c0 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
1f7d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1f7e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1f7f0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1f800 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1f810 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
1f820 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
1f830 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
1f840 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1f850 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
1f860 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f870 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
1f880 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1f890 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
1f8a0 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
1f8b0 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
1f8c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1f8d0 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
1f8e0 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
1f8f0 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
1f900 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
1f910 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
1f920 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
1f930 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
1f940 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
1f950 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
1f960 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
1f970 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
1f980 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
1f990 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
1f9a0 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
1f9b0 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ger.)^.**.** The
1f9c0 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53   [SQLITE_TRACE_S
1f9d0 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  IZE_LIMIT] compi
1f9e0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63  le-time option c
1f9f0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69  an be used to li
1fa00 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74  mit.** the lengt
1fa10 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61  h of [bound para
1fa20 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e  meter] expansion
1fa30 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f   in the output o
1fa40 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  f sqlite3_trace(
1fa50 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )..**.** ^The ca
1fa60 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1fa70 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1fa80 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
1fa90 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
1faa0 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
1fab0 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
1fac0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
1fad0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
1fae0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
1faf0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
1fb00 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
1fb10 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
1fb20 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
1fb30 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
1fb40 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
1fb50 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1fb60 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
1fb70 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
1fb80 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
1fb90 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
1fba0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
1fbb0 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
1fbc0 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
1fbd0 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
1fbe0 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
1fbf0 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
1fc00 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
1fc10 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
1fc20 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1fc30 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
1fc40 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
1fc50 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
1fc60 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
1fc70 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  k.  The.** sqlit
1fc80 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e  e3_profile() fun
1fc90 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ction is conside
1fca0 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
1fcb0 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65   and is.** subje
1fcc0 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
1fcd0 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
1fce0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
1fcf0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
1fd00 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
1fd10 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
1fd20 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
1fd30 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
1fd40 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
1fd50 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
1fd60 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
1fd70 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
1fd80 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
1fd90 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1fda0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
1fdb0 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
1fdc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
1fdd0 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
1fde0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
1fdf0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
1fe00 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
1fe10 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
1fe20 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
1fe30 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
1fe40 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
1fe50 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
1fe60 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
1fe70 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
1fe80 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
1fe90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
1fea0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
1feb0 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
1fec0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1fed0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
1fee0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
1fef0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
1ff00 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
1ff10 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
1ff20 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
1ff30 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
1ff40 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
1ff50 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
1ff60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1ff70 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
1ff80 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
1ff90 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
1ffa0 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20  the approximate 
1ffb0 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
1ffc0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
1ffd0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
1ffe0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
1fff0 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
20000 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
20010 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
20020 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c  k X.  ^If N is l
20030 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65  ess than one the
20040 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a  n the progress.*
20050 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73  * handler is dis
20060 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  abled..**.** ^On
20070 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
20080 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
20090 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
200a0 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
200b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
200c0 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
200d0 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
200e0 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
200f0 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
20100 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
20110 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
20120 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
20130 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
20140 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
20150 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
20160 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
20170 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
20180 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
20190 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
201a0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
201b0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
201c0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
201d0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
201e0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
201f0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
20200 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
20210 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
20220 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
20230 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
20240 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
20250 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
20260 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
20270 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
20280 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
20290 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
202a0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
202b0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
202c0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
202d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
202e0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
202f0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
20300 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
20310 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20320 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
20330 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
20340 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
20350 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f  h..**.*/.SQLITE_
20360 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
20370 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
20380 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
20390 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
203a0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
203b0 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
203c0 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
203d0 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
203e0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
203f0 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
20400 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73  database file as
20410 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
20420 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  e .** filename a
20430 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
20440 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
20450 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
20460 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
20470 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
20480 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
20490 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
204a0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
204b0 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
204c0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
204d0 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
204e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
204f0 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
20500 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
20510 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
20520 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
20530 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
20540 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
20550 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
20560 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
20570 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
20580 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
20590 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
205a0 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
205b0 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
205c0 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
205d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
205e0 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
205f0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
20600 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
20610 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
20620 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
20630 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
20640 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
20650 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
20660 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
20670 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
20680 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
20690 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
206a0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
206b0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
206c0 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
206d0 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
206e0 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
206f0 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
20700 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
20710 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
20720 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
20730 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
20740 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
20750 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69   the database wi
20760 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a  ll be UTF-8 if.*
20770 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
20780 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
20790 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
207a0 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e  and.** UTF-16 in
207b0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
207c0 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65   order if sqlite
207d0 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73  3_open16() is us
207e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  ed..**.** Whethe
207f0 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
20800 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
20810 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
20820 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
20830 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
20840 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20850 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
20860 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
20870 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
20880 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
20890 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
208a0 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
208b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
208c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
208d0 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
208e0 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
208f0 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
20900 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
20910 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
20920 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
20930 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
20940 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
20950 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20960 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
20970 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
20980 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20990 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
209a0 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
209b0 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
209c0 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
209d0 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
209e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
209f0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
20a00 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
20a10 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
20a20 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b  AREDCACHE],.** [
20a30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
20a40 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f  ATECACHE], and/o
20a50 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  r [SQLITE_OPEN_U
20a60 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  RI] flags:)^.**.
20a70 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
20a80 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
20a90 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
20aa0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
20ab0 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
20ac0 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
20ad0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
20ae0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
20af0 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
20b00 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
20b10 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
20b20 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
20b30 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
20b40 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
20b50 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
20b60 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
20b70 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
20b80 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
20b90 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
20ba0 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
20bb0 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
20bc0 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
20bd0 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
20be0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
20bf0 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
20c00 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
20c10 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
20c20 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
20c30 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
20c40 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
20c50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
20c60 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
20c70 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
20c80 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
20c90 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
20ca0 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69  and is created i
20cb0 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
20cc0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
20cd0 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
20ce0 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
20cf0 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
20d00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
20d10 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
20d20 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
20d30 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
20d40 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
20d50 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
20d60 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
20d70 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
20d80 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
20d90 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  ve optionally co
20da0 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65  mbined with othe
20db0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  r.** [SQLITE_OPE
20dc0 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c  N_READONLY | SQL
20dd0 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d  ITE_OPEN_* bits]
20de0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
20df0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
20e00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
20e10 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
20e20 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
20e30 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
20e40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20e50 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
20e60 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
20e70 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
20e80 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
20e90 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
20ea0 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
20eb0 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
20ec0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
20ed0 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
20ee0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
20ef0 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
20f00 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
20f10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20f20 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
20f30 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
20f40 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
20f50 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
20f60 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
20f70 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
20f80 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
20f90 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
20fa0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
20fb0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
20fc0 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
20fd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20fe0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
20ff0 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
21000 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
21010 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
21020 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
21030 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
21040 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
21050 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
21060 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
21070 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
21080 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
21090 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
210a0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
210b0 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
210c0 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
210d0 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
210e0 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
210f0 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
21100 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
21110 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
21120 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
21130 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
21140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
21150 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
21160 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
21170 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
21180 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
21190 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
211a0 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
211b0 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
211c0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
211d0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
211e0 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
211f0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
21200 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
21210 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
21220 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
21230 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
21240 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
21250 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
21260 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
21270 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
21280 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
21290 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
212a0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
212b0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
212c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
212d0 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
212e0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
212f0 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
21300 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
21310 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
21320 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
21330 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
21340 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
21350 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
21360 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
21370 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
21380 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
21390 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
213a0 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
213b0 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
213c0 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
213d0 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
213e0 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
213f0 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
21400 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
21410 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
21420 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
21430 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
21440 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
21450 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
21460 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
21470 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
21480 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
21490 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
214a0 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
214b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
214c0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
214d0 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   [[URI filenames
214e0 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
214f0 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c  ()]] <h3>URI Fil
21500 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  enames</h3>.**.*
21510 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e  * ^If [URI filen
21520 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74  ame] interpretat
21530 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  ion is enabled, 
21540 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  and the filename
21550 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67   argument.** beg
21560 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22  ins with "file:"
21570 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e  , then the filen
21580 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74  ame is interpret
21590 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52  ed as a URI. ^UR
215a0 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e  I.** filename in
215b0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
215c0 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b  enabled if the [
215d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
215e0 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20   flag is.** set 
215f0 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  in the fourth ar
21600 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
21610 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20  3_open_v2(), or 
21620 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65  if it has.** bee
21630 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c  n enabled global
21640 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ly using the [SQ
21650 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
21660 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65   option with the
21670 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
21680 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72  fig()] method or
21690 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
216a0 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65  USE_URI] compile
216b0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
216c0 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65   As of SQLite ve
216d0 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49  rsion 3.7.7, URI
216e0 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
216f0 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e  retation is turn
21700 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66  ed off.** by def
21710 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65  ault, but future
21720 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
21730 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65  ite might enable
21740 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   URI filename.**
21750 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
21760 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65  by default.  See
21770 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   "[URI filenames
21780 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ]" for additiona
21790 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
217a0 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65  ..**.** URI file
217b0 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64  names are parsed
217c0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46   according to RF
217d0 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20  C 3986. ^If the 
217e0 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a  URI contains an.
217f0 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68  ** authority, th
21800 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69  en it must be ei
21810 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74  ther an empty st
21820 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69  ring or the stri
21830 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73  ng .** "localhos
21840 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68  t". ^If the auth
21850 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20  ority is not an 
21860 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
21870 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20  "localhost", an 
21880 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74  .** error is ret
21890 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c  urned to the cal
218a0 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65  ler. ^The fragme
218b0 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  nt component of 
218c0 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72  a URI, if .** pr
218d0 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65  esent, is ignore
218e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
218f0 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63   uses the path c
21900 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20  omponent of the 
21910 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20  URI as the name 
21920 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65  of the disk file
21930 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69  .** which contai
21940 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ns the database.
21950 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65   ^If the path be
21960 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20  gins with a '/' 
21970 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74  character, .** t
21980 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70  hen it is interp
21990 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f  reted as an abso
219a0 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74  lute path. ^If t
219b0 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74  he path does not
219c0 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20   begin .** with 
219d0 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74  a '/' (meaning t
219e0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74  hat the authorit
219f0 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69  y section is omi
21a00 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52  tted from the UR
21a10 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70  I).** then the p
21a20 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ath is interpret
21a30 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65  ed as a relative
21a40 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77   path. .** ^On w
21a50 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73  indows, the firs
21a60 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
21a70 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20  n absolute path 
21a80 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73  .** is a drive s
21a90 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e  pecification (e.
21aa0 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20  g. "C:")..**.** 
21ab0 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79  [[core URI query
21ac0 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a   parameters]].**
21ad0 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   The query compo
21ae0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61  nent of a URI ma
21af0 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65  y contain parame
21b00 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e  ters that are in
21b10 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74  terpreted.** eit
21b20 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74  her by SQLite it
21b30 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56  self, or by a [V
21b40 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20  FS | custom VFS 
21b50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e  implementation].
21b60 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
21b70 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77  prets the follow
21b80 69 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 20  ing three query 
21b90 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
21ba0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
21bb0 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
21bc0 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
21bd0 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
21be0 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
21bf0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
21c00 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
21c10 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
21c20 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
21c30 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
21c40 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
21c50 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
21c60 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
21c70 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
21c80 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
21c90 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
21ca0 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
21cb0 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
21cc0 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
21cd0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
21ce0 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
21cf0 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
21d00 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
21d10 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
21d20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
21d30 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
21d40 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
21d50 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
21d60 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
21d70 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
21d80 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
21d90 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
21da0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
21db0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
21dc0 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
21dd0 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
21de0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
21df0 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
21e00 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
21e10 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
21e20 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
21e30 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
21e40 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
21e50 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
21e60 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
21e70 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
21e80 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
21e90 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
21ea0 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
21eb0 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
21ec0 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
21ed0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
21ee0 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
21ef0 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
21f00 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
21f10 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
21f20 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
21f30 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
21f40 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
21f50 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
21f60 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
21f70 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
21f80 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
21f90 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
21fa0 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
21fb0 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
21fc0 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
21fd0 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
21fe0 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
21ff0 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
22000 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
22010 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
22020 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
22030 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
22040 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
22050 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
22060 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
22070 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
22080 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
22090 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
220a0 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
220b0 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
220c0 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
220d0 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
220e0 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
220f0 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
22100 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
22110 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
22120 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
22130 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
22140 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
22150 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
22160 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
22170 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
22180 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
22190 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
221a0 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
221b0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
221c0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
221d0 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
221e0 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
221f0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
22200 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
22210 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
22220 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
22230 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
22240 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
22250 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
22260 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
22270 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
22280 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
22290 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
222a0 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
222b0 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
222c0 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
222d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
222e0 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
222f0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
22300 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
22310 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
22320 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
22330 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
22340 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
22350 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
22360 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
22370 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
22380 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
22390 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
223a0 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
223b0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
223c0 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c  HE flag..** </ul
223d0 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79  >.**.** ^Specify
223e0 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70  ing an unknown p
223f0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
22400 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
22410 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20  of a URI is not 
22420 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75  an.** error.  Fu
22430 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
22440 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e   SQLite might un
22450 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f  derstand additio
22460 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  nal query.** par
22470 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b  ameters.  See "[
22480 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
22490 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65   with special me
224a0 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d  aning to SQLite]
224b0 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  " for.** additio
224c0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
224d0 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
224e0 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d  ename examples]]
224f0 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d   <h3>URI filenam
22500 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a  e examples</h3>.
22510 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  **.** <table bor
22520 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65  der="1" align=ce
22530 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67  nter cellpadding
22540 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  =5>.** <tr><th> 
22550 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74  URI filenames <t
22560 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74  h> Results.** <t
22570 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
22580 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
22590 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66        Open the f
225a0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
225b0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
225c0 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  ectory..** <tr><
225d0 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
225e0 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a  red/data.db<br>.
225f0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
22600 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  :///home/fred/da
22610 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20  ta.db <br> .**  
22620 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c          file://l
22630 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72  ocalhost/home/fr
22640 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
22650 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
22660 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62    Open the datab
22670 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  ase file "/home/
22680 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a  fred/data.db"..*
22690 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
226a0 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f  //darkstar/home/
226b0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64  fred/data.db <td
226c0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
226d0 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74  n error. "darkst
226e0 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63  ar" is not a rec
226f0 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74  ognized authorit
22700 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74  y..** <tr><td st
22710 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65  yle="white-space
22720 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20  :nowrap"> .**   
22730 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43         file:///C
22740 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e  :/Documents%20an
22750 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65  d%20Settings/fre
22760 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64  d/Desktop/data.d
22770 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69  b.**     <td> Wi
22780 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e  ndows only: Open
22790 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
227a0 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65  db" on fred's de
227b0 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a  sktop on drive.*
227c0 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e  *          C:. N
227d0 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30  ote that the %20
227e0 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69   escaping in thi
227f0 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74  s example is not
22800 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20   strictly .**   
22810 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79         necessary
22820 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74   - space charact
22830 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ers can be used 
22840 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20  literally.**    
22850 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c        in URI fil
22860 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c  enames..** <tr><
22870 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
22880 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70  ?mode=ro&cache=p
22890 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20  rivate <td> .** 
228a0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
228b0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
228c0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
228d0 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f  ctory for read-o
228e0 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20  nly access..**  
228f0 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65          Regardle
22900 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
22910 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68   not shared-cach
22920 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65  e mode is enable
22930 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
22940 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20   default, use a 
22950 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a  private cache..*
22960 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
22970 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
22980 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f  db?vfs=unix-nolo
22990 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  ck <td>.**      
229a0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
229b0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
229c0 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
229d0 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f  ial VFS "unix-no
229e0 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  lock"..** <tr><t
229f0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
22a00 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74  mode=readonly <t
22a10 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
22a20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f  An error. "reado
22a30 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61  nly" is not a va
22a40 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74  lid option for t
22a50 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65  he "mode" parame
22a60 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ter..** </table>
22a70 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61  .**.** ^URI hexa
22a80 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
22a90 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61  equences (%HH) a
22aa0 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74  re supported wit
22ab0 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64  hin the path and
22ac0 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  .** query compon
22ad0 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41  ents of a URI. A
22ae0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
22af0 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e  ape sequence con
22b00 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65  sists of a.** pe
22b10 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22  rcent sign - "%"
22b20 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65   - followed by e
22b30 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64  xactly two hexad
22b40 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a  ecimal digits .*
22b50 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20  * specifying an 
22b60 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65  octet value. ^Be
22b70 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72  fore the path or
22b80 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
22b90 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69  s of a.** URI fi
22ba0 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72  lename are inter
22bb0 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65  preted, they are
22bc0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
22bd0 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a  TF-8 and all .**
22be0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
22bf0 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65  ape sequences re
22c00 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67  placed by a sing
22c10 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69  le byte containi
22c20 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73  ng the.** corres
22c30 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49  ponding octet. I
22c40 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67  f this process g
22c50 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61  enerates an inva
22c60 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  lid UTF-8 encodi
22c70 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  ng,.** the resul
22c80 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
22c90 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
22ca0 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
22cb0 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
22cc0 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
22cd0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
22ce0 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
22cf0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
22d00 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
22d10 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
22d20 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
22d30 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
22d40 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
22d50 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
22d60 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
22d70 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
22d80 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
22d90 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
22da0 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
22db0 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
22dc0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
22dd0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
22de0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
22df0 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
22e00 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
22e10 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
22e20 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
22e30 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
22e40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
22e50 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
22e60 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65  v2().  Otherwise
22e70 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
22e80 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
22e90 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
22ea0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
22eb0 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65  y fail..**.** Se
22ec0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
22ed0 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d  _temp_directory]
22ee0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
22ef0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
22f00 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
22f10 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
22f20 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
22f30 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
22f40 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
22f50 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
22f60 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
22f70 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
22f80 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
22f90 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
22fa0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
22fb0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
22fc0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
22fd0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
22fe0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
22ff0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
23000 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
23010 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
23020 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
23030 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
23040 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
23050 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
23060 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
23070 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
23080 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
23090 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
230a0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
230b0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
230c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
230d0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
230e0 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
230f0 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
23100 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
23110 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
23120 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
23130 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
23140 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
23150 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
23160 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
23170 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
23180 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
23190 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
231a0 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
231b0 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
231c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
231d0 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
231e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
231f0 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
23200 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
23210 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
23220 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
23230 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
23240 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
23250 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
23260 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
23270 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
23280 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
23290 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
232a0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
232b0 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
232c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
232d0 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
232e0 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
232f0 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
23300 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
23310 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
23320 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
23330 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
23340 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
23350 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
23360 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
23370 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
23380 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
23390 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
233a0 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
233b0 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
233c0 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
233d0 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
233e0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
233f0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
23400 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
23410 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
23420 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
23430 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
23440 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
23450 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
23460 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
23470 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
23480 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
23490 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
234a0 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
234b0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
234c0 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
234d0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
234e0 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
234f0 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
23500 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
23510 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
23520 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
23530 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
23540 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
23550 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
23560 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
23570 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
23580 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
23590 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
235a0 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
235b0 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
235c0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
235d0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
235e0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
235f0 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
23600 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
23610 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
23620 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
23630 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
23640 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
23650 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
23660 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
23670 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
23680 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
23690 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
236a0 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
236b0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
236c0 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
236d0 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
236e0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
236f0 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
23700 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
23710 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
23720 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
23730 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
23740 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
23750 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
23760 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
23770 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
23780 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
23790 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
237a0 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
237b0 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
237c0 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
237d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
237e0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
237f0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
23800 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
23810 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
23820 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
23830 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
23840 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
23850 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
23860 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
23870 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
23880 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
23890 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
238a0 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
238b0 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
238c0 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
238d0 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
238e0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
238f0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
23900 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
23910 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
23920 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
23930 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
23940 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
23950 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49  r *zParam);.SQLI
23960 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
23970 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63  e3_uri_boolean(c
23980 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
23990 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
239a0 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75  aram, int bDefau
239b0 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  lt);.SQLITE_API 
239c0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
239d0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
239e0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e  const char*, con
239f0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
23a00 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a  3_int64);.../*.*
23a10 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
23a20 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
23a30 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
23a40 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
23a50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
23a60 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
23a70 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
23a80 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
23a90 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
23aa0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
23ab0 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
23ac0 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
23ad0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
23ae0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23af0 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
23b00 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
23b10 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
23b20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
23b30 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
23b40 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
23b50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
23b60 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
23b70 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
23b80 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
23b90 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
23ba0 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
23bb0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
23bc0 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
23bd0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
23be0 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
23bf0 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
23c00 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
23c10 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
23c20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
23c30 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
23c40 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
23c50 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
23c60 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
23c70 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
23c80 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
23c90 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
23ca0 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
23cb0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
23cc0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
23cd0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
23ce0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
23cf0 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
23d00 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
23d10 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
23d20 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
23d30 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
23d40 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
23d50 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
23d60 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
23d70 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
23d80 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
23d90 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
23da0 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
23db0 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ions.)^.**.** ^T
23dc0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  he sqlite3_errst
23dd0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  r() interface re
23de0 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73  turns the Englis
23df0 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a  h-language text.
23e00 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65  ** that describe
23e10 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f  s the [result co
23e20 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a  de], as UTF-8..*
23e30 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
23e40 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
23e50 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
23e60 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
23e70 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f  y.** and must no
23e80 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68  t be freed by th
23e90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e  e application)^.
23ea0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
23eb0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
23ec0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
23ed0 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
23ee0 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
23ef0 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
23f00 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
23f10 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
23f20 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
23f30 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
23f40 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
23f50 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
23f60 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
23f70 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
23f80 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
23f90 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
23fa0 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
23fb0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
23fc0 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
23fd0 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
23fe0 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
23ff0 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
24000 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
24010 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
24020 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
24030 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
24040 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
24050 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
24060 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
24070 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
24080 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
24090 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
240a0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
240b0 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
240c0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
240d0 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
240e0 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
240f0 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
24100 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
24110 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
24120 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
24130 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
24140 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
24150 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
24160 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
24170 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
24180 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
24190 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
241a0 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
241b0 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
241c0 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49   be set..*/.SQLI
241d0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
241e0 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
241f0 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f  e3 *db);.SQLITE_
24200 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
24210 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
24220 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53  (sqlite3 *db);.S
24230 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
24240 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
24250 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
24260 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
24270 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
24280 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
24290 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
242a0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
242b0 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a  3_errstr(int);..
242c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
242d0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
242e0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
242f0 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
24300 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
24310 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
24320 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
24330 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
24340 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
24350 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
24360 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
24370 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f  is variously kno
24380 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65  wn as a "prepare
24390 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  d statement" or 
243a0 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53  a.** "compiled S
243b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  QL statement" or
243c0 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74   simply as a "st
243d0 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20  atement"..**.** 
243e0 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
243f0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
24400 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
24410 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
24420 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
24430 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
24440 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
24450 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
24460 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
24470 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
24480 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
24490 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   [host parameter
244a0 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
244b0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
244c0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
244d0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
244e0 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
244f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24500 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
24510 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
24520 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  et the statement
24530 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24540 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
24550 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
24560 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
24570 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
24580 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
24590 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
245a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
245b0 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
245c0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65  </ol>.**.** Refe
245d0 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69  r to documentati
245e0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
245f0 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66   methods above f
24600 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
24610 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
24620 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24630 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
24640 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
24650 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
24660 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a  time Limits.**.*
24670 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
24680 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
24690 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
246a0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
246b0 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
246c0 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
246d0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
246e0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
246f0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
24700 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24710 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
24720 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
24730 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
24740 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
24750 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
24760 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
24770 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
24780 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
24790 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
247a0 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
247b0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
247c0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
247d0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
247e0 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
247f0 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
24800 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
24810 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
24820 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
24830 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
24840 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
24850 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
24860 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
24870 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
24880 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
24890 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
248a0 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
248b0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
248c0 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
248d0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
248e0 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
248f0 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
24900 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
24910 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
24920 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
24930 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
24940 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
24950 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
24960 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
24970 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
24980 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
24990 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
249a0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
249b0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
249c0 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
249d0 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
249e0 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
249f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
24a00 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
24a10 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
24a20 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
24a30 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
24a40 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
24a50 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
24a60 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
24a70 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
24a80 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
24a90 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
24aa0 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
24ab0 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
24ac0 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
24ad0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
24ae0 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
24af0 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
24b00 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
24b10 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
24b20 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
24b30 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
24b40 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
24b50 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
24b60 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
24b70 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
24b80 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
24b90 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
24ba0 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
24bb0 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
24bc0 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
24bd0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
24be0 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
24bf0 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
24c00 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
24c10 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
24c20 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
24c30 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
24c40 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
24c50 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
24c60 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
24c70 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
24c80 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
24c90 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
24ca0 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
24cb0 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
24cc0 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
24cd0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
24ce0 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
24cf0 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
24d00 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
24d10 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
24d20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
24d30 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
24d40 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
24d50 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
24d60 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
24d70 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
24d80 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
24d90 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
24da0 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
24db0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
24dc0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
24dd0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
24de0 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
24df0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
24e00 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ases..*/.SQLITE_
24e10 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
24e20 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
24e30 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
24e40 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
24e50 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
24e60 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
24e70 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
24e80 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
24e90 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
24ea0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
24eb0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
24ec0 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
24ed0 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
24ee0 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
24ef0 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
24f00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
24f10 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
24f20 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
24f30 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
24f40 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
24f50 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
24f60 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
24f70 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
24f80 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
24f90 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
24fa0 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
24fb0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
24fc0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
24fd0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
24fe0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
24ff0 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
25000 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
25010 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
25020 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
25030 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
25040 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
25050 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
25060 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
25070 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
25080 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
25090 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
250a0 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
250b0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
250c0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
250d0 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
250e0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
250f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25100 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
25110 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
25120 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
25130 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
25140 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
25150 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
25160 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
25170 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
25180 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
25190 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
251a0 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
251b0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
251c0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
251d0 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
251e0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
251f0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
25200 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
25210 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
25220 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
25230 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
25240 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25250 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
25260 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
25270 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
25280 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
25290 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
252a0 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
252b0 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
252c0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
252d0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
252e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
252f0 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
25300 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
25310 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25320 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
25330 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
25340 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
25350 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
25360 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
25370 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
25380 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
25390 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
253a0 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
253b0 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
253c0 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
253d0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
253e0 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
253f0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
25400 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
25410 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
25420 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
25430 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
25440 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25450 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
25460 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
25470 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
25480 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25490 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
254a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
254b0 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
254c0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
254d0 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
254e0 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
254f0 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
25500 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25510 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
25520 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
25530 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25540 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
25550 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
25560 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
25570 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
25580 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
25590 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
255a0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
255b0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
255c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
255d0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
255e0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
255f0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
25600 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
25610 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
25620 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
25630 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
25640 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
25650 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
25660 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
25670 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
25680 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
25690 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
256a0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
256b0 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
256c0 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
256d0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
256e0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
256f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
25700 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
25710 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
25720 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
25730 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
25740 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
25750 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
25760 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
25770 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
25780 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
25790 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
257a0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
257b0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
257c0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
257d0 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
257e0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
257f0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
25800 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
25810 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25820 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
25830 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
25840 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25850 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
25860 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
25870 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25880 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
25890 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
258a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
258b0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
258c0 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
258d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
258e0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
258f0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
25900 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25910 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
25920 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
25930 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
25940 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
25950 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
25960 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
25970 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
25980 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
25990 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
259a0 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
259b0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
259c0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
259d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
259e0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
259f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
25a00 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
25a10 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
25a20 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
25a30 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
25a40 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25a50 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
25a60 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
25a70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
25a80 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
25a90 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
25aa0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
25ab0 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
25ac0 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
25ad0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
25ae0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
25af0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
25b00 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
25b10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
25b20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
25b30 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
25b40 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
25b50 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
25b60 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
25b70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25b80 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
25b90 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
25ba0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
25bb0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
25bc0 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
25bd0 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
25be0 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
25bf0 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
25c00 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
25c10 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
25c20 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
25c30 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
25c40 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
25c50 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
25c60 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
25c70 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
25c80 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
25c90 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
25ca0 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
25cb0 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
25cc0 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
25cd0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
25ce0 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
25cf0 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
25d00 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
25d10 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
25d20 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
25d30 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
25d40 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
25d50 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
25d60 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
25d70 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
25d80 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
25d90 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
25da0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
25db0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
25dc0 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
25dd0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
25de0 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73  minator bytes as
25df0 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69   this saves SQLi
25e00 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74  te from having t
25e10 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79  o.** make a copy
25e20 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   of the input st
25e30 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
25e40 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
25e50 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
25e60 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
25e70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
25e80 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
25e90 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
25ea0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
25eb0 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
25ec0 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
25ed0 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
25ee0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
25ef0 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
25f00 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
25f10 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
25f20 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
25f30 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
25f40 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
25f50 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
25f60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25f70 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
25f80 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
25f90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
25fa0 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
25fb0 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
25fc0 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
25fd0 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
25fe0 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
25ff0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
26000 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
26010 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
26020 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
26030 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
26040 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
26050 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
26060 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
26070 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
26080 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
26090 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
260a0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
260b0 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
260c0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
260d0 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
260e0 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
260f0 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
26100 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
26110 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
26120 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
26130 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
26140 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
26150 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
26160 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
26170 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
26180 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
26190 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
261a0 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
261b0 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
261c0 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
261d0 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
261e0 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
261f0 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
26200 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
26210 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
26220 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
26230 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
26240 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
26250 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
26260 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
26270 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
26280 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
26290 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
262a0 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
262b0 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
262c0 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
262d0 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
262e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
262f0 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
26300 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
26310 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
26320 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
26330 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
26340 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
26350 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
26360 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
26370 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
26380 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
26390 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
263a0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
263b0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
263c0 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
263d0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
263e0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
263f0 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53  n. As many as [S
26400 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41  QLITE_MAX_SCHEMA
26410 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69  _RETRY].** retri
26420 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65  es will occur be
26430 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65  fore sqlite3_ste
26440 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64  p() gives up and
26450 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
26460 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  r..** </li>.**.*
26470 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
26480 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
26490 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
264a0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
264b0 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
264c0 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
264d0 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
264e0 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
264f0 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
26500 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
26510 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
26520 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
26530 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
26540 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
26550 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
26560 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
26570 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
26580 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
26590 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
265a0 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
265b0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
265c0 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
265d0 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
265e0 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
265f0 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
26600 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
26610 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
26620 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
26630 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
26640 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
26650 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
26660 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
26670 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
26680 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
26690 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
266a0 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
266b0 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
266c0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
266d0 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
266e0 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
266f0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
26700 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
26710 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
26720 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
26730 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
26740 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
26750 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
26760 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
26770 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
26780 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
26790 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
267a0 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
267b0 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
267c0 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
267d0 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
267e0 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
267f0 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
26800 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
26810 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
26820 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
26830 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
26840 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
26850 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
26860 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
26870 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
26880 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
26890 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
268a0 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
268b0 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
268c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
268d0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
268e0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
268f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
26900 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
26910 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
26920 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
26930 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
26940 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
26950 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
26960 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
26970 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
26980 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
26990 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
269a0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
269b0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
269c0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
269d0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
269e0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
269f0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
26a00 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
26a10 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
26a20 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
26a30 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
26a40 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
26a50 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26a60 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
26a70 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
26a80 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
26a90 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
26aa0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
26ab0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
26ac0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
26ad0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
26ae0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
26af0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
26b00 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
26b10 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
26b20 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
26b30 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
26b40 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
26b50 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
26b60 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
26b70 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
26b80 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
26b90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
26ba0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
26bb0 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
26bc0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
26bd0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
26be0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
26bf0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
26c00 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
26c10 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
26c20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
26c30 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
26c40 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
26c50 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
26c60 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
26c70 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
26c80 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
26c90 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
26ca0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
26cb0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
26cc0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
26cd0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
26ce0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
26cf0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
26d00 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
26d10 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
26d20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
26d30 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
26d40 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
26d50 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
26d60 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
26d70 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
26d80 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
26d90 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
26da0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
26db0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
26dc0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
26dd0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
26de0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
26df0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
26e00 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
26e10 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
26e20 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
26e30 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
26e40 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
26e50 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
26e60 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  L.**.** ^This in
26e70 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
26e80 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
26e90 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
26ea0 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
26eb0 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
26ec0 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
26ed0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
26ee0 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
26ef0 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
26f00 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
26f10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
26f20 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
26f30 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
26f40 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
26f50 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
26f60 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
26f70 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
26f80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
26f90 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
26fa0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69  QL Statement Wri
26fb0 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65  tes The Database
26fc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
26fd0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
26fe0 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
26ff0 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
27000 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
27010 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
27020 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27030 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
27040 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
27050 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
27060 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
27070 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
27080 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
27090 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
270a0 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
270b0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
270c0 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
270d0 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
270e0 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
270f0 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
27100 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
27110 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
27120 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
27130 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
27140 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
27150 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
27160 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
27170 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
27180 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
27190 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
271a0 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
271b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
271c0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
271d0 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
271e0 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
271f0 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
27200 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
27210 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
27220 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
27230 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
27240 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
27250 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
27260 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
27270 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
27280 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
27290 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
272a0 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
272b0 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
272c0 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
272d0 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
272e0 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
272f0 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
27300 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
27310 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
27320 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
27330 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
27340 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
27350 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
27360 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
27370 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
27380 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
27390 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
273a0 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
273b0 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
273c0 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
273d0 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
273e0 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
273f0 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
27400 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
27410 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
27420 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
27430 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
27440 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
27450 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
27460 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
27470 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
27480 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
27490 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
274a0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
274b0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
274c0 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53  es on disk..*/.S
274d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
274e0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
274f0 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  nly(sqlite3_stmt
27500 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
27510 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
27520 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72  mine If A Prepar
27530 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73  ed Statement Has
27540 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a   Been Reset.**.*
27550 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
27560 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65  tmt_busy(S) inte
27570 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
27580 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
27590 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
275a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
275b0 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20  as been stepped 
275c0 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73  at least once us
275d0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
275e0 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61  _step(S)] but ha
275f0 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d  s not run to com
27600 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68  pletion and/or h
27610 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20  as not .** been 
27620 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c  reset using [sql
27630 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20  ite3_reset(S)]. 
27640 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
27650 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e  mt_busy(S).** in
27660 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27670 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20  false if S is a 
27680 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
27690 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a  f S is not a .**
276a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
276b0 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74  d is not a point
276c0 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70  er to a valid [p
276d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
276e0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68  t].** object, th
276f0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
27700 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
27710 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
27720 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rable..**.** Thi
27730 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
27740 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69  be used in combi
27750 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  nation [sqlite3_
27760 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20  next_stmt()].** 
27770 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72  to locate all pr
27780 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27790 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
277a0 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  h a database .**
277b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
277c0 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20   are in need of 
277d0 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68  being reset.  Th
277e0 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a  is can be used,.
277f0 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** for example, 
27800 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f  in diagnostic ro
27810 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68  utines to search
27820 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a   for prepared .*
27830 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  * statements tha
27840 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20  t are holding a 
27850 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e  transaction open
27860 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
27870 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
27880 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74  _busy(sqlite3_st
27890 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
278a0 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c  I3REF: Dynamical
278b0 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
278c0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
278d0 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
278e0 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
278f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27900 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
27910 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
27920 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27930 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
27940 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
27950 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
27960 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
27970 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
27980 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
27990 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
279a0 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20  ues it stores.  
279b0 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69  ^Values stored i
279c0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
279d0 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62  objects.** can b
279e0 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
279f0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
27a00 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
27a10 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
27a20 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
27a30 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
27a40 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
27a50 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
27a60 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
27a70 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
27a80 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
27a90 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
27aa0 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
27ab0 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
27ac0 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
27ad0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
27ae0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
27af0 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
27b00 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
27b10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
27b20 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
27b30 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  es.** whether or
27b40 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73   not it requires
27b50 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
27b60 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  ite3_value..**.*
27b70 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f  * The terms "pro
27b80 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70  tected" and "unp
27b90 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20  rotected" refer 
27ba0 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  to whether or no
27bb0 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20  t.** a mutex is 
27bc0 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e  held.  An intern
27bd0 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
27be0 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
27bf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
27c00 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
27c10 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
27c20 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
27c30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
27c40 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
27c50 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
27c60 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
27c70 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
27c80 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
27c90 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
27ca0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
27cb0 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
27cc0 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
27cd0 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
27ce0 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
27cf0 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
27d00 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
27d10 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
27d20 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
27d30 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
27d40 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
27d50 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
27d60 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
27d70 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
27d80 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
27d90 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
27da0 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
27db0 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
27dc0 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
27dd0 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
27de0 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
27df0 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
27e00 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
27e10 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
27e20 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
27e30 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
27e40 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
27e50 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
27e60 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
27e70 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
27e80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27e90 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
27ea0 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
27eb0 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
27ec0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
27ed0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
27ee0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
27ef0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
27f00 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
27f10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27f20 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
27f30 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
27f40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
27f50 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
27f60 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
27f70 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
27f80 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
27f90 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
27fa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
27fb0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
27fc0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
27fd0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
27fe0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
27ff0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
28000 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
28010 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
28020 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
28030 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28040 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
28050 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
28060 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
28070 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28080 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  F: SQL Function 
28090 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a  Context Object.*
280a0 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
280b0 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
280c0 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
280d0 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
280e0 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
280f0 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e  ntext object.  ^
28100 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
28110 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
28120 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
28130 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
28140 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
28150 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
28160 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
28170 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
28180 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
28190 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
281a0 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
281b0 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
281c0 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
281d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
281e0 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
281f0 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
28200 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
28210 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
28220 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
28230 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
28240 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
28250 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
28260 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
28270 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
28280 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
28290 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
282a0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
282b0 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
282c0 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
282d0 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
282e0 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
282f0 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  d Statements.** 
28300 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
28310 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
28320 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
28330 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
28340 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
28350 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
28360 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
28370 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
28380 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ing}.**.** ^(In 
28390 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
283a0 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20  t text input to 
283b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
283c0 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
283d0 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65  ariants,.** lite
283e0 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c  rals may be repl
283f0 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d  aced by a [param
28400 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68  eter] that match
28410 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77  es one of follow
28420 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73  ing.** templates
28430 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
28440 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
28450 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
28460 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56  VVV.** <li>  @VV
28470 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  V.** <li>  $VVV.
28480 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
28490 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20  n the templates 
284a0 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65  above, NNN repre
284b0 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72  sents an integer
284c0 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64   literal,.** and
284d0 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20   VVV represents 
284e0 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  an alphanumeric 
284f0 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e  identifier.)^  ^
28500 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
28510 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
28520 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
28530 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
28540 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
28550 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
28560 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
28570 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
28580 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
28590 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
285a0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
285b0 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
285c0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
285d0 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a  tines is always.
285e0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
285f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
28600 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
28610 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
28620 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
28630 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
28640 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  s..**.** ^The se
28650 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
28660 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
28670 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
28680 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54  to be set..** ^T
28690 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
286a0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
286b0 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57   index of 1.  ^W
286c0 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  hen the same nam
286d0 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ed.** SQL parame
286e0 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65  ter is used more
286f0 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f   than once, seco
28700 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
28710 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73  t.** occurrences
28720 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69   have the same i
28730 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73  ndex as the firs
28740 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a  t occurrence..**
28750 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20   ^The index for 
28760 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
28770 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
28780 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
28790 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
287a0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
287b0 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
287c0 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66   ^The index.** f
287d0 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65  or "?NNN" parame
287e0 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75  ters is the valu
287f0 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68  e of NNN..** ^Th
28800 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
28810 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
28820 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  d the [sqlite3_l
28830 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d  imit()].** param
28840 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d  eter [SQLITE_LIM
28850 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
28860 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c  ER] (default val
28870 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20  ue: 999)..**.** 
28880 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
28890 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
288a0 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
288b0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
288c0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
288d0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
288e0 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
288f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
28900 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  t16().** or sqli
28910 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
28920 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
28930 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  r then the fourt
28940 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  h parameter.** i
28950 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68  s ignored and th
28960 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20  e end result is 
28970 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69  the same as sqli
28980 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e  te3_bind_null().
28990 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73  .**.** ^(In thos
289a0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
289b0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
289c0 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
289d0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
289e0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
289f0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
28a00 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
28a10 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
28a20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
28a30 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
28a40 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
28a50 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
28a60 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.)^.** ^If the 
28a70 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
28a80 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
28a90 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
28aa0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
28ab0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
28ac0 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68   then the length
28ad0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
28ae0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
28af0 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
28b00 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
28b10 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20  rminator..** If 
28b20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
28b30 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
28b40 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e  bind_blob() is n
28b50 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a  egative, then.**
28b60 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
28b70 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
28b80 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  f a non-negative
28b90 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
28ba0 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  r is provided to
28bb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
28bc0 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  xt().** or sqlit
28bd0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
28be0 20 74 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d   then that param
28bf0 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65  eter must be the
28c00 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20   byte offset.** 
28c10 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
28c20 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f  rminator would o
28c30 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68  ccur assuming th
28c40 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55  e string were NU
28c50 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e  L.** terminated.
28c60 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
28c70 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74  racters occur at
28c80 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65   byte offsets le
28c90 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20  ss than .** the 
28ca0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75  value of the fou
28cb0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68  rth parameter th
28cc0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
28cd0 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69   string value wi
28ce0 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d  ll.** contain em
28cf0 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68  bedded NULs.  Th
28d00 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  e result of expr
28d10 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e  essions involvin
28d20 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74  g strings.** wit
28d30 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
28d40 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
28d50 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
28d60 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
28d70 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
28d80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
28d90 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
28da0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
28db0 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
28dc0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
28dd0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
28de0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
28df0 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
28e00 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
28e10 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
28e20 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
28e30 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
28e40 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
28e50 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
28e60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
28e70 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  ob(),.** sqlite3
28e80 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72  _bind_text(), or
28e90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
28ea0 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a  xt16() fails.  .
28eb0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
28ec0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
28ed0 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
28ee0 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
28ef0 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
28f00 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
28f10 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
28f20 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
28f30 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
28f40 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
28f50 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  o be freed..** ^
28f60 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
28f70 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
28f80 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
28f90 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
28fa0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
28fb0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
28fc0 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
28fd0 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
28fe0 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
28ff0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
29000 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
29010 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
29020 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
29030 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
29040 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
29050 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
29060 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
29070 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
29080 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
29090 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
290a0 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
290b0 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
290c0 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
290d0 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
290e0 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
290f0 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
29100 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
29110 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
29120 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
29130 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
29140 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
29150 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
29160 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
29170 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
29180 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
29190 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
291a0 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
291b0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
291c0 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
291d0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
291e0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
291f0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
29200 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
29210 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
29220 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
29230 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
29240 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
29250 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
29260 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
29270 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
29280 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
29290 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
292a0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
292b0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
292c0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
292d0 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
292e0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
292f0 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
29300 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
29310 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
29320 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
29330 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
29340 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
29350 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
29360 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
29370 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
29380 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29390 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
293a0 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
293b0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
293c0 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
293d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
293e0 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
293f0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
29400 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
29410 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
29420 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
29430 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
29440 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
29450 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
29460 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
29470 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
29480 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
29490 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
294a0 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
294b0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
294c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
294d0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
294e0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
294f0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29500 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
29510 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29520 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
29530 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
29540 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
29550 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
29560 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
29570 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
29580 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
29590 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
295a0 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
295b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
295c0 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c  nt, double);.SQL
295d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
295e0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
295f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
29600 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
29610 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
29620 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
29630 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
29640 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c  ite3_int64);.SQL
29650 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
29660 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
29670 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29680 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
29690 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
296a0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
296b0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
296c0 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  ar*, int n, void
296d0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
296e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
296f0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
29700 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29710 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
29720 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
29730 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
29740 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
29750 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
29760 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
29770 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
29780 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
29790 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
297a0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
297b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
297c0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
297d0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
297e0 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
297f0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
29800 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
29810 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
29820 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
29830 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
29840 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29850 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
29860 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
29870 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
29880 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
29890 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
298a0 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
298b0 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
298c0 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
298d0 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
298e0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
298f0 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
29900 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
29910 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
29920 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
29930 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
29940 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
29950 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
29960 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
29970 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
29980 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
29990 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
299a0 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
299b0 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
299c0 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
299d0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
299e0 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
299f0 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
29a00 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
29a10 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
29a20 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
29a30 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
29a40 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
29a50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29a60 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
29a70 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
29a80 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
29a90 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
29aa0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
29ab0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29ac0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
29ad0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
29ae0 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
29af0 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
29b00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29b10 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29b20 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
29b30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
29b40 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
29b50 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
29b60 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
29b70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29b80 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
29b90 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
29ba0 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
29bb0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
29bc0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
29bd0 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
29be0 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
29bf0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
29c00 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
29c10 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
29c20 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
29c30 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
29c40 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
29c50 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
29c60 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
29c70 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
29c80 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
29c90 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
29ca0 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
29cb0 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
29cc0 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
29cd0 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
29ce0 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
29cf0 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
29d00 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
29d10 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
29d20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
29d30 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
29d40 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
29d50 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
29d60 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
29d70 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
29d80 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
29d90 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
29da0 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
29db0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
29dc0 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
29dd0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
29de0 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
29df0 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
29e00 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
29e10 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
29e20 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
29e30 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
29e40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29e50 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
29e60 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
29e70 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
29e80 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
29e90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
29ea0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
29eb0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
29ec0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
29ed0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53  r_index()]..*/.S
29ee0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
29ef0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
29f00 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
29f10 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
29f20 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
29f30 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
29f40 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
29f50 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
29f60 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
29f70 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
29f80 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
29f90 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
29fa0 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
29fb0 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
29fc0 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
29fd0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
29fe0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
29ff0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2a000 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
2a010 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
2a020 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
2a030 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
2a040 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
2a050 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
2a060 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
2a070 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
2a080 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2a090 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
2a0a0 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
2a0b0 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
2a0c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2a0d0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
2a0e0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2a0f0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2a100 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2a110 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2a120 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2a130 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2a140 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a150 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
2a160 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2a170 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a180 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
2a190 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
2a1a0 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
2a1b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2a1c0 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
2a1d0 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
2a1e0 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
2a1f0 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
2a200 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
2a210 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
2a220 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
2a230 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
2a240 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2a250 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
2a260 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a270 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69  nt]..** ^Use thi
2a280 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
2a290 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
2a2a0 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
2a2b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2a2c0 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
2a2d0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
2a2e0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2a2f0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2a300 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
2a310 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
2a320 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
2a330 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2a340 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2a350 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
2a360 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2a370 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73  tatement]. ^This
2a380 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2a390 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
2a3a0 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
2a3b0 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
2a3c0 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
2a3d0 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
2a3e0 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  DATE])..**.** Se
2a3f0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2a400 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
2a410 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2a420 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a430 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2a440 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2a450 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
2a460 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
2a470 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
2a480 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2a490 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
2a4a0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
2a4b0 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
2a4c0 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
2a4d0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
2a4e0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
2a4f0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
2a500 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
2a510 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2a520 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2a530 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2a540 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
2a550 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2a560 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
2a570 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2a580 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2a590 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
2a5a0 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
2a5b0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2a5c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a5d0 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
2a5e0 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
2a5f0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2a600 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
2a610 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
2a620 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
2a630 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
2a640 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
2a650 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
2a660 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
2a670 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
2a680 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
2a690 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a6a0 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
2a6b0 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
2a6c0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
2a6d0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
2a6e0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
2a6f0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
2a700 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
2a710 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2a720 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
2a730 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
2a740 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
2a750 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
2a760 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2a770 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
2a780 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
2a790 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
2a7a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
2a7b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
2a7c0 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
2a7d0 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
2a7e0 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
2a7f0 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
2a800 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
2a810 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
2a820 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
2a830 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2a840 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2a850 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
2a860 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
2a870 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2a880 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
2a890 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
2a8a0 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
2a8b0 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
2a8c0 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
2a8d0 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
2a8e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
2a8f0 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
2a900 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
2a910 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
2a920 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
2a930 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53  o the next..*/.S
2a940 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2a950 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2a960 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
2a970 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
2a980 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2a990 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2a9a0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
2a9b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a9c0 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
2a9d0 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
2a9e0 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
2a9f0 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Result.**.** ^Th
2aa00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
2aa10 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
2aa20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
2aa30 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
2aa40 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
2aa50 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
2aa60 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
2aa70 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
2aa80 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
2aa90 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
2aaa0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
2aab0 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
2aac0 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
2aad0 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
2aae0 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
2aaf0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
2ab00 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
2ab10 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
2ab20 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
2ab30 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
2ab40 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
2ab50 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
2ab60 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
2ab70 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
2ab80 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
2ab90 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
2aba0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2abb0 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
2abc0 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
2abd0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
2abe0 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
2abf0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
2ac00 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
2ac10 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2ac20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
2ac30 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
2ac40 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
2ac50 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2ac60 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
2ac70 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
2ac80 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
2ac90 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
2aca0 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
2acb0 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
2acc0 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54  coding..**.** ^T
2acd0 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
2ace0 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
2acf0 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
2ad00 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
2ad10 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
2ad20 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
2ad30 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
2ad40 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e  ment to these in
2ad50 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
2ad60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ad70 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
2ad80 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
2ad90 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
2ada0 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
2adb0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
2adc0 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
2add0 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
2ade0 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
2adf0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
2ae00 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20   ^The left-most 
2ae10 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e  column is column
2ae20 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75   0 for these rou
2ae30 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tines..**.** ^If
2ae40 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2ae50 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
2ae60 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
2ae70 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
2ae80 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
2ae90 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
2aea0 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
2aeb0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2aec0 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
2aed0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
2aee0 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
2aef0 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
2af00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2af10 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
2af20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65   ^Otherwise, the
2af30 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
2af40 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
2af50 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
2af60 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20  e,.** or column 
2af70 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
2af80 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
2af90 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
2afa0 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20  ** ^As with all 
2afb0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
2afc0 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e  s, those whose n
2afd0 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31  ames end with "1
2afe0 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
2aff0 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
2b000 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65  ngs and the othe
2b010 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
2b020 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
2b030 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
2b040 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
2b050 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
2b060 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
2b070 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
2b080 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
2b090 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
2b0a0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a  essor symbol..**
2b0b0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
2b0c0 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
2b0d0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
2b0e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
2b0f0 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
2b100 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
2b110 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
2b120 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2b130 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2b140 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
2b150 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
2b160 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
2b170 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
2b180 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
2b190 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2b1a0 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
2b1b0 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
2b1c0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
2b1d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b1e0 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
2b1f0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
2b200 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2b210 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2b220 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53   undefined..*/.S
2b230 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2b240 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2b250 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2b260 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2b270 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2b280 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2b290 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2b2a0 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
2b2b0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2b2c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2b2d0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2b2e0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
2b2f0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2b300 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2b310 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2b320 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2b330 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
2b340 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2b350 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2b360 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2b370 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
2b380 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2b390 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2b3a0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2b3b0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2b3c0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2b3d0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2b3e0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
2b3f0 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
2b400 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2b410 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
2b420 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
2b430 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b440 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
2b450 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
2b460 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2b470 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
2b480 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
2b490 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
2b4a0 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
2b4b0 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
2b4c0 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
2b4d0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2b4e0 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
2b4f0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2b500 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
2b510 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
2b520 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
2b530 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2b540 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
2b550 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2b560 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
2b570 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
2b580 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2b590 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2b5a0 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
2b5b0 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
2b5c0 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
2b5d0 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
2b5e0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
2b5f0 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
2b600 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
2b610 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
2b620 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
2b630 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
2b640 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
2b650 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
2b660 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
2b670 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
2b680 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
2b690 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
2b6a0 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
2b6b0 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
2b6c0 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
2b6d0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
2b6e0 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
2b6f0 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
2b700 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
2b710 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
2b720 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
2b730 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
2b740 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
2b750 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
2b760 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
2b770 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
2b780 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
2b790 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
2b7a0 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
2b7b0 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
2b7c0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
2b7d0 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
2b7e0 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
2b7f0 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
2b800 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
2b810 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
2b820 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
2b830 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
2b840 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
2b850 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
2b860 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54  values..*/.SQLIT
2b870 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2b880 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2b890 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
2b8a0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2b8b0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2b8c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2b8d0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
2b8e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2b8f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b900 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
2b910 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
2b920 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
2b930 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b940 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
2b950 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
2b960 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2b970 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2b980 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2b990 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
2b9a0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
2b9b0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
2b9c0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
2b9d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b9e0 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
2b9f0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
2ba00 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
2ba10 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
2ba20 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
2ba30 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
2ba40 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
2ba50 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
2ba60 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
2ba70 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
2ba80 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
2ba90 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
2baa0 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
2bab0 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
2bac0 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
2bad0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2bae0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2baf0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
2bb00 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
2bb10 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
2bb20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2bb30 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2bb40 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
2bb50 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
2bb60 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
2bb70 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
2bb80 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
2bb90 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
2bba0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2bbb0 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
2bbc0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
2bbd0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
2bbe0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2bbf0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2bc00 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
2bc10 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
2bc20 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
2bc30 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
2bc40 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2bc50 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
2bc60 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
2bc70 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
2bc80 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
2bc90 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
2bca0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
2bcb0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
2bcc0 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
2bcd0 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
2bce0 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
2bcf0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
2bd00 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
2bd10 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
2bd20 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
2bd30 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
2bd40 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
2bd50 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
2bd60 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
2bd70 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
2bd80 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
2bd90 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
2bda0 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
2bdb0 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
2bdc0 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
2bdd0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
2bde0 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
2bdf0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
2be00 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
2be10 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
2be20 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
2be30 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
2be40 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
2be50 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
2be60 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
2be70 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
2be80 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
2be90 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
2bea0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
2beb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
2bec0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
2bed0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
2bee0 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
2bef0 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
2bf00 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
2bf10 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
2bf20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
2bf30 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
2bf40 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2bf50 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
2bf60 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2bf70 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
2bf80 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
2bf90 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
2bfa0 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
2bfb0 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
2bfc0 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
2bfd0 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
2bfe0 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
2bff0 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
2c000 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
2c010 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
2c020 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
2c030 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
2c040 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
2c050 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
2c060 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
2c070 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
2c080 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
2c090 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
2c0a0 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
2c0b0 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
2c0c0 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
2c0d0 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
2c0e0 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
2c0f0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
2c100 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
2c110 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
2c120 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
2c130 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
2c140 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
2c150 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
2c160 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
2c170 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
2c180 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
2c190 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
2c1a0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
2c1b0 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
2c1c0 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
2c1d0 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
2c1e0 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
2c1f0 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
2c200 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2c210 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
2c220 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2c230 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
2c240 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2c250 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
2c260 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
2c270 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
2c280 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
2c290 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
2c2a0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2c2b0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2c2c0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
2c2d0 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
2c2e0 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
2c2f0 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
2c300 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
2c310 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2c320 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
2c330 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
2c340 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
2c350 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
2c360 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
2c370 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
2c380 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
2c390 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
2c3a0 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
2c3b0 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
2c3c0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
2c3d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2c3e0 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
2c3f0 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
2c400 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
2c410 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
2c420 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
2c430 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
2c440 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
2c450 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
2c460 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
2c470 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
2c480 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65  as required afte
2c490 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
2c4a0 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
2c4b0 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  ng.** other than
2c4c0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65   [SQLITE_ROW] be
2c4d0 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
2c4e0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
2c4f0 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
2c500 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
2c510 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
2c520 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
2c530 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
2c540 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20  _reset()] would 
2c550 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
2c560 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
2c570 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  urn from.** sqli
2c580 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
2c590 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33   after version 3
2c5a0 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33  .6.23.1, sqlite3
2c5b0 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
2c5c0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2c5d0 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
2c5e0 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
2c5f0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
2c600 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
2c610 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
2c620 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
2c630 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
2c640 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
2c650 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
2c660 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
2c670 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
2c680 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
2c690 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
2c6a0 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
2c6b0 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
2c6c0 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
2c6d0 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
2c6e0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
2c6f0 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
2c700 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
2c710 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
2c720 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
2c730 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
2c740 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2c750 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
2c760 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
2c770 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
2c780 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
2c790 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
2c7a0 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
2c7b0 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
2c7c0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
2c7d0 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
2c7e0 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
2c7f0 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
2c800 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
2c810 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2c820 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
2c830 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
2c840 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
2c850 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
2c860 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
2c870 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
2c880 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
2c890 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
2c8a0 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
2c8b0 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
2c8c0 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
2c8d0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
2c8e0 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
2c8f0 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
2c900 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
2c910 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
2c920 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2c930 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c940 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
2c950 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
2c960 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
2c970 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
2c980 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2c990 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
2c9a0 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
2c9b0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
2c9c0 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
2c9d0 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
2c9e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2c9f0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
2ca00 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
2ca10 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
2ca20 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2ca30 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
2ca40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2ca50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ca60 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
2ca70 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
2ca80 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2ca90 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2caa0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2cab0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2cac0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2cad0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77  e.** current row
2cae0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2caf0 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
2cb00 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
2cb10 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74   ^If prepared st
2cb20 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e  atement P does n
2cb30 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20  ot have results 
2cb40 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a  ready to return.
2cb50 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f  ** (via calls to
2cb60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
2cb70 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74  lumn_int | sqlit
2cb80 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f  e3_column_*()] o
2cb90 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29  f.** interfaces)
2cba0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61   then sqlite3_da
2cbb0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75  ta_count(P) retu
2cbc0 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73  rns 0..** ^The s
2cbd0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2cbe0 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73  t(P) routine als
2cbf0 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50  o returns 0 if P
2cc00 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2cc10 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  er..** ^The sqli
2cc20 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2cc30 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2cc40 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69  s 0 if the previ
2cc50 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ous call to.** [
2cc60 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2cc70 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2cc80 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73  E_DONE].  ^The s
2cc90 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2cca0 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74  t(P).** will ret
2ccb0 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20  urn non-zero if 
2ccc0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2ccd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
2cce0 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  P) returned.** [
2ccf0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63  SQLITE_ROW], exc
2cd00 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20  ept in the case 
2cd10 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69  of the [PRAGMA i
2cd20 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75  ncremental_vacuu
2cd30 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61  m].** where it a
2cd40 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65  lways returns ze
2cd50 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74  ro since each st
2cd60 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69  ep of that multi
2cd70 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20  -step.** pragma 
2cd80 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e  returns 0 column
2cd90 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  s of data..**.**
2cda0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2cdb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2cdc0 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ()].*/.SQLITE_AP
2cdd0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  I int sqlite3_da
2cde0 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
2cdf0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2ce00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ce10 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
2ce20 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
2ce30 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
2ce40 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
2ce50 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
2ce60 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
2ce70 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
2ce80 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2ce90 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
2cea0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2ceb0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
2cec0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2ced0 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
2cee0 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
2cef0 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
2cf00 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
2cf10 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2cf20 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
2cf30 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
2cf40 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
2cf50 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
2cf60 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
2cf70 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
2cf80 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
2cf90 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
2cfa0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
2cfb0 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
2cfc0 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
2cfd0 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
2cfe0 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
2cff0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
2d000 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
2d010 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
2d020 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
2d030 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2d040 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
2d050 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
2d060 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2d070 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
2d080 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
2d090 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
2d0a0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
2d0b0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2d0c0 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
2d0d0 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
2d0e0 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
2d0f0 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
2d100 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
2d110 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
2d120 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
2d130 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
2d140 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2d150 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
2d160 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
2d170 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22  the "result set"
2d180 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2d190 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2d1a0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2d1b0 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
2d1c0 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
2d1d0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
2d1e0 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
2d1f0 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63  ry.  ^In every c
2d200 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
2d210 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
2d220 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
2d230 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d240 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
2d250 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
2d260 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
2d270 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
2d280 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
2d290 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2d2a0 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
2d2b0 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
2d2c0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
2d2d0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
2d2e0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
2d2f0 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
2d300 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
2d310 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65  e returned. ^The
2d320 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
2d330 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2d340 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
2d350 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62   0..** ^The numb
2d360 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2d370 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20   the result can 
2d380 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
2d390 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2d3a0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e  column_count()].
2d3b0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
2d3c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
2d3d0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
2d3e0 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
2d3f0 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
2d400 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
2d410 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
2d420 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
2d430 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
2d440 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
2d450 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
2d460 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
2d470 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
2d480 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2d490 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
2d4a0 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
2d4b0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
2d4c0 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
2d4d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2d4e0 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
2d4f0 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
2d500 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
2d510 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2d520 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
2d530 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d540 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2d550 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
2d560 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
2d570 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2d580 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
2d590 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2d5a0 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
2d5b0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2d5c0 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
2d5d0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
2d5e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2d5f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2d600 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
2d610 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
2d620 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
2d630 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
2d640 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
2d650 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
2d660 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2d670 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2d680 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2d690 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
2d6a0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
2d6b0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
2d6c0 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
2d6d0 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
2d6e0 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
2d6f0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
2d700 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
2d710 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
2d720 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
2d730 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
2d740 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
2d750 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
2d760 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
2d770 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
2d780 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
2d790 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2d7a0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
2d7b0 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
2d7c0 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
2d7d0 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
2d7e0 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
2d7f0 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
2d800 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2d810 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
2d820 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2d830 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2d840 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
2d850 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
2d860 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
2d870 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
2d880 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
2d890 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
2d8a0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
2d8b0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
2d8c0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
2d8d0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
2d8e0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
2d8f0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2d900 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
2d910 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2d920 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2d930 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
2d940 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
2d950 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2d960 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
2d970 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
2d980 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
2d990 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
2d9a0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
2d9b0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2d9c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2d9d0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2d9e0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2d9f0 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2da00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2da10 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
2da20 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2da30 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2da40 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2da50 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
2da60 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
2da70 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2da80 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2da90 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2daa0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
2dab0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2dac0 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  es() returns zer
2dad0 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  o..**.** ^If the
2dae0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
2daf0 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  B or UTF-16 stri
2db00 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
2db10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2db20 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  16().** routine 
2db30 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2db40 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2db50 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2db60 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2db70 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38  esult is a UTF-8
2db80 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
2db90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2dba0 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a  es16() converts.
2dbb0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
2dbc0 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e   UTF-16 and then
2dbd0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2dbe0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
2dbf0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2dc00 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
2dc10 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
2dc20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2dc30 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2dc40 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2dc50 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2dc60 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20  lue to a UTF-16 
2dc70 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2dc80 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
2dc90 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2dca0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
2dcb0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
2dcc0 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
2dcd0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2dce0 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
2dcf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  .**.** ^The valu
2dd00 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
2dd10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2dd20 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20  ytes()] and .** 
2dd30 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2dd40 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f  bytes16()] do no
2dd50 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
2dd60 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61  ro terminators a
2dd70 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
2dd80 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f  the string.  ^Fo
2dd90 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
2dda0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2ddb0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2ddc0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
2ddd0 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
2dde0 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65  n_bytes16()] are
2ddf0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
2de00 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
2de10 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
2de20 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2de30 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69  ers..**.** ^Stri
2de40 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
2de50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2de60 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
2de70 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2de80 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
2de90 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
2dea0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
2deb0 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  ated.  ^The retu
2dec0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
2ded0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2dee0 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
2def0 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73  o-length BLOB is
2df00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2df10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65  .**.** ^The obje
2df20 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
2df30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2df40 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
2df50 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2df60 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2df70 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65  ect.  An unprote
2df80 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2df90 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79  ue object.** may
2dfa0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
2dfb0 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  th [sqlite3_bind
2dfc0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
2dfd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2dfe0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
2dff0 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
2e000 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2e010 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2e020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2e030 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2e040 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
2e050 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
2e060 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
2e070 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
2e080 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
2e090 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2e0a0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
2e0b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2e0c0 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68  ytes()], then th
2e0d0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2e0e0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
2e0f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
2e100 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
2e110 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
2e120 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e   appropriate.  ^
2e130 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
2e140 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
2e150 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
2e160 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
2e170 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
2e180 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
2e190 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2e1a0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
2e1b0 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
2e1c0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
2e1d0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2e1e0 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
2e1f0 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
2e200 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
2e210 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
2e220 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
2e230 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
2e240 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
2e250 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
2e260 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
2e270 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
2e280 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
2e290 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
2e2a0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
2e2b0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
2e2c0 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
2e2d0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2e2e0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2e2f0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
2e300 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2e310 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
2e320 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2e330 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2e340 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
2e350 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
2e360 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
2e370 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
2e380 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
2e390 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
2e3a0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
2e3b0 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
2e3c0 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
2e3d0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2e3e0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2e3f0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
2e400 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
2e410 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2e420 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
2e430 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
2e440 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
2e450 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
2e460 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
2e470 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
2e480 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
2e490 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2e4a0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2e4b0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
2e4c0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
2e4d0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
2e4e0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
2e4f0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  LOB    <td> [CAS
2e500 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74  T] to BLOB.** <t
2e510 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2e520 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2e530 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
2e540 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
2e550 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2e560 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
2e570 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
2e580 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2e590 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2e5a0 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
2e5b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2e5c0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
2e5d0 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
2e5e0 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
2e5f0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2e600 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2e610 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
2e620 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
2e630 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
2e640 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
2e650 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
2e660 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
2e670 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
2e680 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
2e690 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
2e6a0 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
2e6b0 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
2e6c0 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
2e6d0 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
2e6e0 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
2e6f0 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
2e700 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
2e710 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
2e720 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
2e730 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
2e740 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
2e750 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
2e760 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
2e770 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
2e780 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
2e790 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
2e7a0 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
2e7b0 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
2e7c0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2e7d0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
2e7e0 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
2e7f0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
2e800 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
2e810 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2e820 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
2e830 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2e840 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
2e850 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2e860 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
2e870 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
2e880 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
2e890 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
2e8a0 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
2e8b0 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
2e8c0 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
2e8d0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2e8e0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2e8f0 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
2e900 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2e910 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
2e920 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2e930 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
2e940 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
2e950 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
2e960 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
2e970 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
2e980 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
2e990 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2e9a0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
2e9b0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2e9c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2e9d0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2e9e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2e9f0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2ea00 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
2ea10 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
2ea20 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
2ea30 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
2ea40 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2ea50 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
2ea60 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2ea70 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2ea80 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2ea90 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
2eaa0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2eab0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2eac0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2ead0 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
2eae0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
2eaf0 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
2eb00 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
2eb10 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
2eb20 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
2eb30 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
2eb40 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
2eb50 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
2eb60 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
2eb70 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2eb80 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
2eb90 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
2eba0 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
2ebb0 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
2ebc0 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
2ebd0 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
2ebe0 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
2ebf0 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
2ec00 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
2ec10 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
2ec20 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
2ec30 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
2ec40 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
2ec50 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
2ec60 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
2ec70 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
2ec80 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
2ec90 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
2eca0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
2ecb0 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
2ecc0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
2ecd0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2ece0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2ecf0 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
2ed00 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2ed10 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
2ed20 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
2ed30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2ed40 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2ed50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ed60 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
2ed70 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2ed80 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
2ed90 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2eda0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
2edb0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2edc0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
2edd0 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
2ede0 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
2edf0 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
2ee00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2ee10 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
2ee20 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
2ee30 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
2ee40 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
2ee50 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
2ee60 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
2ee70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ee80 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
2ee90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2eea0 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
2eeb0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
2eec0 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
2eed0 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
2eee0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2eef0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
2ef00 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
2ef10 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
2ef20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ef30 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
2ef40 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
2ef50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ef60 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
2ef70 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2ef80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
2ef90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
2efa0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
2efb0 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
2efc0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
2efd0 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
2efe0 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
2eff0 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
2f000 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2f010 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2f020 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2f030 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
2f040 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
2f050 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
2f060 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
2f070 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
2f080 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2f090 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
2f0a0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
2f0b0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
2f0c0 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
2f0d0 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
2f0e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2f0f0 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
2f100 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2f110 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20  ]..**.** ^(If a 
2f120 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2f130 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
2f140 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
2f150 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
2f160 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2f170 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
2f180 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
2f190 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
2f1a0 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
2f1b0 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
2f1c0 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
2f1d0 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
2f1e0 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
2f1f0 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
2f200 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2f210 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
2f220 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
2f230 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a  TE_NOMEM].)^.*/.
2f240 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2f250 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2f260 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
2f270 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2f280 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2f290 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2f2a0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
2f2b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2f2c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2f2d0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2f2e0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
2f2f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2f300 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f  );.SQLITE_API do
2f310 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
2f320 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
2f330 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2f340 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2f350 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2f360 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
2f370 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2f380 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
2f390 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
2f3a0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
2f3b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2f3c0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
2f3d0 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e  API const unsign
2f3e0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2f3f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
2f400 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f410 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
2f420 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2f430 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f440 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
2f450 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2f460 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2f470 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2f480 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f490 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
2f4a0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61  E_API sqlite3_va
2f4b0 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
2f4c0 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
2f4d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2f4e0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
2f4f0 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
2f500 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2f510 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e  t Object.**.** ^
2f520 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
2f530 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
2f540 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
2f550 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
2f560 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2f570 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2f580 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
2f590 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
2f5a0 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
2f5b0 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68  rors.** or if th
2f5c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
2f5d0 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
2f5e0 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
2f5f0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
2f600 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
2f610 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
2f620 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
2f630 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
2f640 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
2f650 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
2f660 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
2f670 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
2f680 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
2f690 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
2f6a0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
2f6b0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
2f6c0 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
2f6d0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
2f6e0 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
2f6f0 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
2f700 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
2f710 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
2f720 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
2f730 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
2f740 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
2f750 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
2f760 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
2f770 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
2f780 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
2f790 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f7a0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
2f7b0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
2f7c0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
2f7d0 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
2f7e0 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
2f7f0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
2f800 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
2f810 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2f820 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
2f830 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
2f840 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
2f850 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
2f860 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f870 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
2f880 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
2f890 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
2f8a0 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
2f8b0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
2f8c0 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
2f8d0 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
2f8e0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
2f8f0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2f900 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
2f910 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
2f920 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
2f930 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
2f940 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
2f950 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
2f960 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
2f970 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
2f980 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
2f990 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
2f9a0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2f9b0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
2f9c0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
2f9d0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2f9e0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2f9f0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2fa00 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
2fa10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2fa20 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
2fa30 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
2fa40 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
2fa50 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
2fa60 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
2fa70 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
2fa80 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
2fa90 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
2faa0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
2fab0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
2fac0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
2fad0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
2fae0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2faf0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
2fb00 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
2fb10 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
2fb20 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
2fb30 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2fb40 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2fb50 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
2fb60 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
2fb70 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
2fb80 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
2fb90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fba0 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
2fbb0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
2fbc0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
2fbd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2fbe0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2fbf0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2fc00 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
2fc10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fc20 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
2fc30 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
2fc40 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
2fc50 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
2fc60 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
2fc70 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
2fc80 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
2fc90 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2fca0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
2fcb0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
2fcc0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2fcd0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2fce0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
2fcf0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
2fd00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2fd10 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
2fd20 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
2fd30 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2fd40 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
2fd50 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
2fd60 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
2fd70 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2fd80 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
2fd90 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
2fda0 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
2fdb0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2fdc0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
2fdd0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2fde0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
2fdf0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2fe00 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
2fe10 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2fe20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2fe30 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
2fe40 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
2fe50 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
2fe60 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
2fe70 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
2fe80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2fe90 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2fea0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
2feb0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2fec0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2fed0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
2fee0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
2fef0 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
2ff00 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
2ff10 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
2ff20 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
2ff30 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
2ff40 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
2ff50 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
2ff60 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
2ff70 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
2ff80 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
2ff90 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2ffa0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
2ffb0 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
2ffc0 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
2ffd0 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
2ffe0 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
2fff0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
30000 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
30010 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
30020 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
30030 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
30040 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
30050 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
30060 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
30070 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
30080 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
30090 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
300a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
300b0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
300c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
300d0 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
300e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
300f0 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
30100 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
30110 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
30120 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
30130 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
30140 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30150 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
30160 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
30170 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
30180 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
30190 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
301a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
301b0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
301c0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
301d0 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
301e0 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
301f0 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
30200 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
30210 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
30220 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
30230 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
30240 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
30250 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
30260 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
30270 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
30280 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
30290 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
302a0 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
302b0 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
302c0 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
302d0 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
302e0 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
302f0 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
30300 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
30310 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
30320 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
30330 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
30340 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
30350 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
30360 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
30370 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
30380 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
30390 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
303a0 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
303b0 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
303c0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
303d0 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
303e0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
303f0 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
30400 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
30410 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
30420 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
30430 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
30440 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
30450 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
30460 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
30470 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
30480 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
30490 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
304a0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
304b0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
304c0 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
304d0 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
304e0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
304f0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
30500 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
30510 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
30520 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
30530 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
30540 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73   should set this
30550 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
30560 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
30570 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f  ] if the functio
30580 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
30590 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71   invokes .** [sq
305a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
305b0 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16le()] on an in
305c0 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  put, or [SQLITE_
305d0 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a  UTF16BE] if the.
305e0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
305f0 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74  n invokes [sqlit
30600 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
30610 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
30620 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  , or.** [SQLITE_
30630 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74  UTF16] if [sqlit
30640 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
30650 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b  )] is used, or [
30660 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20  SQLITE_UTF8].** 
30670 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65  otherwise.  ^The
30680 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
30690 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
306a0 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
306b0 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66  mes using.** dif
306c0 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64  ferent preferred
306d0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c   text encodings,
306e0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
306f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
30700 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f  for.** each enco
30710 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  ding..** ^When m
30720 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
30730 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
30740 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
30750 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
30760 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
30770 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
30780 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
30790 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
307a0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
307b0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
307c0 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f  ameter may optio
307d0 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69  nally be ORed wi
307e0 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  th [SQLITE_DETER
307f0 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20  MINISTIC].** to 
30800 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20  signal that the 
30810 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c  function will al
30820 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
30830 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65  same result give
30840 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e  n.** the same in
30850 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69  puts within a si
30860 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
30870 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75  nt.  Most SQL fu
30880 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64  nctions are.** d
30890 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
308a0 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e  he built-in [ran
308b0 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74  dom()] SQL funct
308c0 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  ion is an exampl
308d0 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69  e of a.** functi
308e0 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64  on that is not d
308f0 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
30900 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20  he SQLite query 
30910 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20  planner is able 
30920 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64  to.** perform ad
30930 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a  ditional optimiz
30940 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d  ations on determ
30950 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e  inistic function
30960 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20  s, so use.** of 
30970 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  the [SQLITE_DETE
30980 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20  RMINISTIC] flag 
30990 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77  is recommended w
309a0 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  here possible..*
309b0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
309c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
309d0 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
309e0 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
309f0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
30a00 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
30a10 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
30a20 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
30a30 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
30a40 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
30a50 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65  ^The sixth, seve
30a60 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70  nth and eighth p
30a70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
30a80 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
30a90 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
30aa0 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
30ab0 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
30ac0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
30ad0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
30ae0 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
30af0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
30b00 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
30b10 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
30b20 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
30b30 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
30b40 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
30b50 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
30b60 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
30b70 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
30b80 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
30b90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
30ba0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
30bb0 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
30bc0 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
30bd0 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
30be0 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
30bf0 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
30c00 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
30c10 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
30c20 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
30c30 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ass NULL pointer
30c40 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  s for all three 
30c50 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
30c60 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  backs..**.** ^(I
30c70 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61  f the ninth para
30c80 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
30c90 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30ca0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  _v2() is not NUL
30cb0 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  L,.** then it is
30cc0 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
30cd0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
30ce0 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a  data pointer. .*
30cf0 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  * The destructor
30d00 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
30d10 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
30d20 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72   deleted, either
30d30 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65   by being.** ove
30d40 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20  rloaded or when 
30d50 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
30d60 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29  nection closes.)
30d70 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75  ^.** ^The destru
30d80 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76  ctor is also inv
30d90 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
30da0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
30db0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
30dc0 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57  2() fails..** ^W
30dd0 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
30de0 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  or callback of t
30df0 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74  he tenth paramet
30e00 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  er is invoked, i
30e10 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61  t.** is passed a
30e20 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
30e30 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79   which is a copy
30e40 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
30e50 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69  ion data .** poi
30e60 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
30e70 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
30e80 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
30e90 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
30ea0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ()..**.** ^It is
30eb0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
30ec0 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
30ed0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
30ee0 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
30ef0 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
30f00 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
30f10 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
30f20 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
30f30 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
30f40 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
30f50 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
30f60 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
30f70 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
30f80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
30f90 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
30fa0 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
30fb0 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
30fc0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
30fd0 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  sed.  ^A functio
30fe0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
30ff0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
31000 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
31010 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
31020 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
31030 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
31040 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
31050 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
31060 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68    ^A function wh
31070 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
31080 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
31090 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
310a0 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
310b0 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
310c0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
310d0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
310e0 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
310f0 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66  erent.  .** ^A f
31100 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
31110 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
31120 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
31130 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
31140 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
31150 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
31160 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
31170 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
31180 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
31190 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
311a0 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69  TF16..**.** ^Bui
311b0 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
311c0 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
311d0 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
311e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
311f0 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  ctions..**.** ^A
31200 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
31210 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
31220 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
31230 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
31240 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
31250 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
31260 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
31270 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
31280 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
31290 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
312a0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
312b0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
312c0 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
312d0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
312e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
312f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
31300 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
31310 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
31320 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
31330 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
31340 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
31350 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
31360 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
31370 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
31380 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
31390 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
313a0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
313b0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
313c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
313d0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
313e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
313f0 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
31400 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
31410 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
31420 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
31430 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
31440 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
31450 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
31460 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
31470 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
31480 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
31490 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
314a0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
314b0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
314c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
314d0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
314e0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
314f0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
31500 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  text*).);.SQLITE
31510 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
31520 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31530 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
31540 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
31550 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
31560 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
31570 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
31580 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
31590 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
315a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
315b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
315c0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
315d0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
315e0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
315f0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
31600 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
31610 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
31620 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
31630 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
31640 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
31650 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
31660 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
31670 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
31680 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
31690 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
316a0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
316b0 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
316c0 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
316d0 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
316e0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
316f0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
31700 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
31710 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
31720 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
31730 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
31740 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
31750 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
31760 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
31770 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
31780 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70       5    /* Dep
31790 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69  recated */.#defi
317a0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
317b0 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
317c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
317d0 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
317e0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
317f0 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67  F: Function Flag
31800 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
31810 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f  nstants may be O
31820 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 74  Red together wit
31830 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
31840 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 72  E_UTF8 | preferr
31850 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
31860 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  ] as the fourth 
31870 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b  argument.** to [
31880 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31890 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  unction()], [sql
318a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
318b0 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
318c0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
318d0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e  _function_v2()].
318e0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
318f0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
31900 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a      0x800../*.**
31910 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65   CAPI3REF: Depre
31920 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a  cated Functions.
31930 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a  ** DEPRECATED.**
31940 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
31950 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61  ons are [depreca
31960 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20  ted].  In order 
31970 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
31980 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
31990 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
319a0 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75  r code, these fu
319b0 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  nctions continue
319c0 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f   .** to be suppo
319d0 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20  rted.  However, 
319e0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
319f0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
31a00 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
31a10 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
31a20 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20   help encourage 
31a30 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a  people to avoid.
31a40 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66  ** using these f
31a50 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65  unctions, we are
31a60 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65   not going to te
31a70 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79  ll you what they
31a80 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20   do..*/.#ifndef 
31a90 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52  SQLITE_OMIT_DEPR
31aa0 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50  ECATED.SQLITE_AP
31ab0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
31ac0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
31ad0 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
31ae0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31af0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
31b00 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
31b10 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
31b20 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
31b30 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
31b40 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
31b50 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
31b60 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
31b70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
31b80 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
31b90 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
31ba0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
31bb0 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
31bc0 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
31bd0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
31be0 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
31bf0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
31c00 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
31c10 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
31c20 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
31c30 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
31c40 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
31c50 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
31c60 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  nt),.           
31c70 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a             void*
31c80 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
31c90 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
31ca0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
31cb0 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
31cc0 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
31cd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
31ce0 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
31cf0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
31d00 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
31d10 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
31d20 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
31d30 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
31d40 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
31d50 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
31d60 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
31d70 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
31d80 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
31d90 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
31da0 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
31db0 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
31dc0 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
31dd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31de0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
31df0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31e00 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
31e10 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
31e20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
31e30 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
31e40 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
31e50 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61  .** The 3rd para
31e60 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
31e70 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
31e80 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
31e90 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
31ea0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
31eb0 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
31ec0 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
31ed0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
31ee0 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
31ef0 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
31f00 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
31f10 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
31f20 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
31f30 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
31f40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
31f50 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
31f60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
31f70 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
31f80 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
31f90 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
31fa0 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
31fb0 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
31fc0 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
31fd0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
31fe0 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
31ff0 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
32000 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
32010 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
32020 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
32030 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
32040 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20  ponding [column 
32050 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
32060 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ].** except that
32070 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73    these routines
32080 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
32090 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
320a0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
320b0 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
320c0 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
320d0 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
320e0 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
320f0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
32100 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32110 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
32120 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
32130 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
32140 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
32150 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
32160 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
32170 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
32180 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
32190 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
321a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
321b0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
321c0 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
321d0 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
321e0 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
321f0 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
32200 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  vely..**.** ^(Th
32210 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
32220 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
32230 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
32240 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
32250 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
32260 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
32270 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
32280 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
32290 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
322a0 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
322b0 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
322c0 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
322d0 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
322e0 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
322f0 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
32300 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
32310 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
32320 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
32330 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
32340 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
32350 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
32360 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
32370 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
32380 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
32390 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
323a0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
323b0 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
323c0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
323d0 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
323e0 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
323f0 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
32400 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
32410 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
32420 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
32430 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
32440 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
32450 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
32460 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
32470 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
32480 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
32490 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
324a0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
324b0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
324c0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
324d0 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
324e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
324f0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
32500 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32510 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
32520 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
32530 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
32540 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
32550 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
32560 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
32570 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
32580 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
32590 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  eters..*/.SQLITE
325a0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
325b0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  *sqlite3_value_b
325c0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  lob(sqlite3_valu
325d0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
325e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
325f0 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
32600 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
32610 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
32620 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
32630 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
32640 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65  QLITE_API double
32650 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
32660 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
32670 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
32680 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  I int sqlite3_va
32690 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
326a0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
326b0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
326c0 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
326d0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
326e0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
326f0 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  I const unsigned
32700 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
32710 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
32720 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
32730 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
32740 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
32750 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
32760 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
32770 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
32780 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32790 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
327a0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
327b0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
327c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
327d0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
327e0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
327f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
32800 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
32810 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
32820 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
32830 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
32840 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
32850 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
32860 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
32870 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
32880 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70  ontext.**.** Imp
32890 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
328a0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
328b0 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
328c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
328d0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
328e0 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
328f0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
32900 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
32910 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
32920 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
32930 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
32940 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
32950 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
32960 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
32970 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
32980 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
32990 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
329a0 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
329b0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
329c0 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
329d0 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
329e0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
329f0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
32a00 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
32a10 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
32a20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
32a30 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
32a40 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
32a50 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
32a60 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
32a70 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
32a80 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
32a90 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
32aa0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
32ab0 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
32ac0 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
32ad0 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
32ae0 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
32af0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
32b00 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
32b10 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
32b20 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
32b30 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
32b40 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
32b50 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
32b60 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
32b70 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
32b80 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
32b90 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
32ba0 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
32bb0 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
32bc0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
32bd0 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
32be0 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
32bf0 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
32c00 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
32c10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32c20 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
32c30 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
32c40 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
32c50 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20  ointer .** when 
32c60 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20  first called if 
32c70 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
32c80 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20  r equal to zero 
32c90 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a  or if a memory.*
32ca0 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72  * allocate error
32cb0 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e   occurs..**.** ^
32cc0 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73  (The amount of s
32cd0 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  pace allocated b
32ce0 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  y sqlite3_aggreg
32cf0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
32d00 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65   is.** determine
32d10 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d  d by the N param
32d20 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75  eter on first su
32d30 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20  ccessful call.  
32d40 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20  Changing the.** 
32d50 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75  value of N in su
32d60 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
32d70 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
32d80 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74  te_context() wit
32d90 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  hin.** the same 
32da0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
32db0 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c  on instance will
32dc0 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20   not resize the 
32dd0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
32de0 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20  tion.)^  Within 
32df0 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
32e00 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f  ack, it is custo
32e10 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e  mary to set.** N
32e20 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73  =0 in calls to s
32e30 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
32e40 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f  _context(C,N) so
32e50 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69   that no .** poi
32e60 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c  ntless memory al
32e70 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e  locations occur.
32e80 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61  .**.** ^SQLite a
32e90 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
32ea0 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
32eb0 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73  located by .** s
32ec0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
32ed0 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20  _context() when 
32ee0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75  the aggregate qu
32ef0 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
32f00 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
32f10 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
32f20 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
32f30 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
32f40 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
32f50 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
32f60 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
32f70 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
32f80 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c   xStep or xFinal
32f90 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
32fa0 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
32fb0 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
32fc0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
32fd0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
32fe0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
32ff0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
33000 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
33010 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
33020 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
33030 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
33040 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
33050 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
33060 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
33070 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
33080 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
33090 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
330a0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
330b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
330c0 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
330d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
330e0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
330f0 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
33100 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
33110 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
33120 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
33130 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
33140 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
33150 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
33160 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33170 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
33180 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
33190 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
331a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
331b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
331c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
331d0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
331e0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
331f0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
33200 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
33210 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33220 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
33230 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
33240 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
33250 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
33260 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
33270 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
33280 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
33290 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
332a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
332b0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
332c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
332d0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
332e0 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  * the pointer to
332f0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
33300 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20  onnection] (the 
33310 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  1st parameter).*
33320 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
33330 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33340 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
33350 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33360 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
33370 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
33380 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
33390 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
333a0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
333b0 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
333c0 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65   sqlite3 *sqlite
333d0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
333e0 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  dle(sqlite3_cont
333f0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
33400 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
33410 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a   Auxiliary Data.
33420 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
33430 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
33440 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67  d by (non-aggreg
33450 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  ate) SQL functio
33460 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
33470 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
33480 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
33490 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
334a0 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
334b0 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
334c0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
334d0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
334e0 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
334f0 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
33500 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
33510 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
33520 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
33530 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
33540 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f   An example.** o
33550 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67  f where this mig
33560 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20  ht be useful is 
33570 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70  in a regular-exp
33580 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67  ression matching
33590 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
335a0 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
335b0 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
335c0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
335d0 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   be stored as.**
335e0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
335f0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70 61  ated with the pa
33600 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a  ttern string.  .
33610 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20  ** Then as long 
33620 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 73  as the pattern s
33630 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68  tring remains th
33640 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63  e same,.** the c
33650 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
33660 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
33670 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
33680 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
33690 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
336a0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
336b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
336c0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
336d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
336e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
336f0 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
33700 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
33710 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
33720 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
33730 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
33740 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
33750 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33760 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  ined function. ^
33770 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  If there is no m
33780 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
33790 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 66  iated with the f
337a0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
337b0 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67  , this sqlite3_g
337c0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
337d0 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
337e0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
337f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33800 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
33810 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66  (C,N,P,X) interf
33820 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20 6d  ace saves P as m
33830 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20  etadata for the 
33840 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
33850 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
33860 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33870 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65  tion.  ^Subseque
33880 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
33890 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
338a0 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50  ta(C,N) return P
338b0 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72   from the most r
338c0 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33  ecent.** sqlite3
338d0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
338e0 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68  ,P,X) call if th
338f0 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 74  e metadata is st
33900 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20  ill valid or.** 
33910 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61  NULL if the meta
33920 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 69  data has been di
33930 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74  scarded..** ^Aft
33940 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20  er each call to 
33950 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
33960 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65  ata(C,N,P,X) whe
33970 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  re X is not NULL
33980 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  ,.** SQLite will
33990 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
339a0 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
339b0 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 72  X with parameter
339c0 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e   P exactly.** on
339d0 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74  ce, when the met
339e0 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72 64  adata is discard
339f0 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  ed..** SQLite is
33a00 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 64   free to discard
33a10 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 74   the metadata at
33a20 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75   any time, inclu
33a30 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  ding: <ul>.** <l
33a40 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  i> when the corr
33a50 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
33a60 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
33a70 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  nges, or.** <li>
33a80 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   when [sqlite3_r
33a90 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
33aa0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
33ab0 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  is called for th
33ac0 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74  e.**      SQL st
33ad0 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c  atement, or.** <
33ae0 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33  li> when sqlite3
33af0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
33b00 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20  s invoked again 
33b10 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 61  on the same para
33b20 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  meter, or.** <li
33b30 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69  > during the ori
33b40 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65  ginal sqlite3_se
33b50 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c  t_auxdata() call
33b60 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a   when a memory .
33b70 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69  **      allocati
33b80 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  on error occurs.
33b90 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e   </ul>)^.**.** N
33ba0 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c  ote the last bul
33bb0 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61  let in particula
33bc0 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74  r.  The destruct
33bd0 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69  or X in .** sqli
33be0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
33bf0 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62  C,N,P,X) might b
33c00 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61  e called immedia
33c10 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65  tely, before the
33c20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
33c30 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
33c40 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73  ace even returns
33c50 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33  .  Hence sqlite3
33c60 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a  _set_auxdata().*
33c70 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c  * should be call
33c80 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20  ed near the end 
33c90 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
33ca0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61  implementation a
33cb0 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  nd the.** functi
33cc0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
33cd0 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b  n should not mak
33ce0 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61  e any use of P a
33cf0 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  fter.** sqlite3_
33d00 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 61  set_auxdata() ha
33d10 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a  s been called..*
33d20 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69  *.** ^(In practi
33d30 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
33d40 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
33d50 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
33d60 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   for.** function
33d70 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
33d80 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   are compile-tim
33d90 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63  e constants, inc
33da0 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a  luding literal.*
33db0 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61  * values and [pa
33dc0 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78  rameters] and ex
33dd0 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73  pressions compos
33de0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
33df0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .)^.**.** These 
33e00 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
33e10 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
33e20 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
33e30 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
33e40 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
33e50 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
33e60 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
33e70 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
33e80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33e90 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
33ea0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
33eb0 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
33ec0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
33ed0 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
33ee0 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
33ef0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33f00 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
33f10 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
33f20 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
33f30 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
33f40 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
33f50 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
33f60 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
33f70 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
33f80 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
33f90 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
33fa0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
33fb0 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
33fc0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
33fd0 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
33fe0 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
33ff0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
34000 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
34010 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
34020 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
34030 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
34040 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
34050 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
34060 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
34070 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
34080 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
34090 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
340a0 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
340b0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
340c0 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
340d0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
340e0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
340f0 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
34100 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
34110 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
34120 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
34130 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
34140 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
34150 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74   compilers..*/.t
34160 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
34170 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
34180 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
34190 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
341a0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
341b0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
341c0 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
341d0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
341e0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
341f0 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
34200 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34210 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
34220 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
34230 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  nction.**.** The
34240 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
34250 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
34260 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
34270 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
34280 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
34290 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
342a0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
342b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
342c0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
342d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
342e0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
342f0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
34300 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
34310 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
34320 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
34330 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
34340 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
34350 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
34360 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
34370 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
34380 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
34390 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
343a0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
343b0 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
343c0 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
343d0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
343e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
343f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34400 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
34410 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
34420 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
34430 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
34440 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
34450 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
34460 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
34470 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
34480 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
34490 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
344a0 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
344b0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
344c0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
344d0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
344e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
344f0 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
34500 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
34510 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
34520 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34530 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
34540 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
34550 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
34560 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
34570 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
34580 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
34590 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
345a0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
345b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
345c0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
345d0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
345e0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
345f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34600 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
34610 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
34620 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
34630 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
34640 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
34650 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34660 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
34670 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34680 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
34690 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
346a0 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
346b0 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
346c0 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
346d0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
346e0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
346f0 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
34700 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
34710 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34720 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
34730 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
34740 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
34750 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
34760 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
34770 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
34780 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
34790 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
347a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
347b0 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
347c0 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
347d0 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
347e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
347f0 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
34800 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
34810 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
34820 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
34830 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
34840 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
34850 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
34860 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
34870 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
34880 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
34890 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
348a0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
348b0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
348c0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
348d0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
348e0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
348f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34900 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
34910 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34920 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
34930 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
34940 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
34950 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
34960 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
34970 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
34980 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
34990 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
349a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
349b0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
349c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
349d0 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
349e0 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
349f0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
34a00 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
34a10 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
34a20 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
34a30 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
34a40 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
34a50 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
34a60 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
34a70 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
34a80 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
34a90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34aa0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
34ab0 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
34ac0 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
34ad0 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
34ae0 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
34af0 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
34b00 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
34b10 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
34b20 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
34b30 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
34b40 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
34b50 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
34b60 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
34b70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34b80 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
34b90 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
34ba0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
34bb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34bc0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
34bd0 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63  oobig() interfac
34be0 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
34bf0 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65  to throw an.** e
34c00 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
34c10 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72  that a string or
34c20 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e   BLOB is too lon
34c30 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a  g to represent..
34c40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34c50 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
34c60 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
34c70 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
34c80 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65  to throw an.** e
34c90 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
34ca0 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
34cb0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
34cc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34cd0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
34ce0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
34cf0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
34d00 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
34d10 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34d20 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
34d30 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
34d40 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
34d50 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
34d60 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  d argument..** ^
34d70 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34d80 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
34d90 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
34da0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
34db0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34dc0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
34dd0 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
34de0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
34df0 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
34e00 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
34e10 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
34e20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34e30 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
34e40 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
34e50 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
34e60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34e70 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
34e80 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
34e90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34ea0 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
34eb0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
34ec0 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
34ed0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
34ee0 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
34ef0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
34f00 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
34f10 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
34f20 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
34f30 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34f40 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
34f50 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
34f60 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
34f70 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
34f80 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
34f90 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
34fa0 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
34fb0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
34fc0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
34fd0 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ely..** ^SQLite 
34fe0 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
34ff0 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
35000 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
35010 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
35020 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
35030 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
35040 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
35050 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
35060 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
35070 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35080 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
35090 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
350a0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
350b0 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
350c0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
350d0 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65  r.** through the
350e0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
350f0 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
35100 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
35110 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
35120 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
35130 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
35140 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
35150 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
35160 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
35170 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
35180 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
35190 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
351a0 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
351b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
351c0 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
351d0 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33  esult.  If the 3
351e0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
351f0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
35200 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65  en it.** must be
35210 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74   the byte offset
35220 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67   into the string
35230 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
35240 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a  erminator would.
35250 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65  ** appear if the
35260 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55   string where NU
35270 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  L terminated.  I
35280 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
35290 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ters occur.** in
352a0 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61   the string at a
352b0 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61   byte offset tha
352c0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74  t is less than t
352d0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
352e0 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  3rd.** parameter
352f0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
35300 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c  ting string will
35310 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
35320 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a  d NULs and the.*
35330 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  * result of expr
35340 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e  essions operatin
35350 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74  g on strings wit
35360 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
35370 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
35380 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
35390 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
353a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
353b0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
353c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
353d0 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
353e0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
353f0 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
35400 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
35410 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
35420 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
35430 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
35440 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
35450 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
35460 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
35470 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
35480 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
35490 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
354a0 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a  nterfaces or to.
354b0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
354c0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
354d0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
354e0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
354f0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
35500 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
35510 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
35520 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
35530 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
35540 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
35550 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70  content of the p
35560 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c  arameter nor cal
35570 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f  l a destructor o
35580 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a  n the content.**
35590 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
355a0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
355b0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
355c0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
355d0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
355e0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
355f0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
35600 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
35610 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
35620 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
35630 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
35640 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
35650 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
35660 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
35670 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
35680 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
35690 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
356a0 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
356b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
356c0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
356d0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
356e0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
356f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
35700 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
35710 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65  to be a copy the
35720 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
35730 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
35740 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
35750 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
35760 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20  meter.  ^The.** 
35770 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
35780 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
35790 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
357a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
357b0 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
357c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
357d0 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
357e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
357f0 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
35800 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
35810 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
35820 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
35830 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
35840 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74  ..** ^A [protect
35850 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
35860 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77  ] object may alw
35870 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72  ays be used wher
35880 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  e an.** [unprote
35890 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
358a0 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65  ue] object is re
358b0 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65  quired, so eithe
358c0 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71  r.** kind of [sq
358d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
358e0 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  ect can be used 
358f0 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66  with this interf
35900 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ace..**.** If th
35910 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
35920 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
35930 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e  hin the differen
35940 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e  t thread.** than
35950 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e   the one contain
35960 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74  ing the applicat
35970 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
35980 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76  tion that receiv
35990 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ed.** the [sqlit
359a0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e  e3_context] poin
359b0 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ter, the results
359c0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
359d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
359e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
359f0 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
35a00 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
35a10 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
35a20 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
35a30 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
35a40 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
35a50 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
35a60 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c  t*, double);.SQL
35a70 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
35a80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35a90 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
35aa0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
35ab0 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
35ac0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
35ad0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71  esult_error16(sq
35ae0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
35af0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
35b00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
35b10 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35b20 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
35b30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
35b40 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
35b50 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35b60 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
35b70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
35b80 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
35b90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35ba0 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
35bb0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
35bc0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
35bd0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35be0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
35bf0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  text*, int);.SQL
35c00 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
35c10 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
35c20 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  4(sqlite3_contex
35c30 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t*, sqlite3_int6
35c40 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  4);.SQLITE_API v
35c50 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35c60 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
35c70 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
35c80 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
35c90 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
35ca0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35cb0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
35cc0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
35cd0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  ));.SQLITE_API v
35ce0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35cf0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
35d00 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
35d10 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
35d20 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
35d30 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
35d40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35d50 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
35d60 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
35d70 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
35d80 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
35d90 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
35da0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35db0 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
35dc0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
35dd0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
35de0 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
35df0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
35e00 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
35e10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
35e20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
35e30 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
35e40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
35e50 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  roblob(sqlite3_c
35e60 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b  ontext*, int n);
35e70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35e80 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c  : Define New Col
35e90 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73  lating Sequences
35ea0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
35eb0 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d  nctions add, rem
35ec0 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61  ove, or modify a
35ed0 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73   [collation] ass
35ee0 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
35ef0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
35f00 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
35f10 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  ied as the first
35f20 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
35f30 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
35f40 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61  e collation is a
35f50 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
35f60 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
35f70 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
35f80 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61  and sqlite3_crea
35f90 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
35fa0 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31  ).** and a UTF-1
35fb0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
35fc0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f  ve byte order fo
35fd0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
35fe0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a  _collation16()..
35ff0 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61  ** ^Collation na
36000 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65  mes that compare
36010 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67   equal according
36020 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72   to [sqlite3_str
36030 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20  nicmp()] are.** 
36040 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65  considered to be
36050 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a   the same name..
36060 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72  **.** ^(The thir
36070 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78  d argument (eTex
36080 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e  tRep) must be on
36090 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
360a0 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ts:.** <ul>.** <
360b0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  li> [SQLITE_UTF8
360c0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
360d0 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20  TE_UTF16LE],.** 
360e0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
360f0 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  16BE],.** <li> [
36100 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f  SQLITE_UTF16], o
36110 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
36120 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
36130 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  ..** </ul>)^.** 
36140 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72  ^The eTextRep ar
36150 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65  gument determine
36160 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f  s the encoding o
36170 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64  f strings passed
36180 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  .** to the colla
36190 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
361a0 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63  llback, xCallbac
361b0 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  k..** ^The [SQLI
361c0 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53  TE_UTF16] and [S
361d0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
361e0 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20  NED] values for 
361f0 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63  eTextRep.** forc
36200 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20  e strings to be 
36210 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76  UTF16 with nativ
36220 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
36230 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
36240 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
36250 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20  ue for eTextRep 
36260 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74  forces strings t
36270 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e  o begin.** on an
36280 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65   even byte addre
36290 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ss..**.** ^The f
362a0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
362b0 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c  pArg, is an appl
362c0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
362d0 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73  nter that is pas
362e0 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  sed.** through a
362f0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
36300 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c  ment to the coll
36310 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
36320 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
36330 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
36340 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69  nt, xCallback, i
36350 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
36360 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
36370 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69  ction..** ^Multi
36380 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ple collating fu
36390 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72  nctions can be r
363a0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
363b0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
363c0 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72  t.** with differ
363d0 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72  ent eTextRep par
363e0 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69  ameters and SQLi
363f0 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63  te will use whic
36400 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  hever.** functio
36410 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c  n requires the l
36420 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
36430 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69  ata transformati
36440 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78  on..** ^If the x
36450 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  Callback argumen
36460 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  t is NULL then t
36470 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
36480 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65  ction is.** dele
36490 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20  ted.  ^When all 
364a0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
364b0 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73  ons having the s
364c0 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c  ame name are del
364d0 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f  eted,.** that co
364e0 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f  llation is no lo
364f0 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a  nger usable..**.
36500 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e  ** ^The collatin
36510 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
36520 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
36530 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ith a copy of th
36540 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69  e pArg .** appli
36550 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
36560 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f  ter and with two
36570 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
36580 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
36590 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65  ed.** by the eTe
365a0 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20  xtRep argument. 
365b0 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
365c0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74  unction must ret
365d0 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65  urn an.** intege
365e0 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69  r that is negati
365f0 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73  ve, zero, or pos
36600 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20  itive.** if the 
36610 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
36620 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c  less than, equal
36630 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20   to, or greater 
36640 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c  than the second,
36650 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
36660 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  .  A collating f
36670 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77  unction must alw
36680 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73  ays return the s
36690 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69  ame answer.** gi
366a0 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70  ven the same inp
366b0 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20  uts.  If two or 
366c0 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  more collating f
366d0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67  unctions are reg
366e0 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68  istered.** to th
366f0 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e  e same collation
36700 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66   name (using dif
36710 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
36720 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c  values) then all
36730 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e  .** must give an
36740 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77   equivalent answ
36750 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20  er when invoked 
36760 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20  with equivalent 
36770 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20  strings..** The 
36780 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36790 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65  on must obey the
367a0 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65   following prope
367b0 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a  rties for all.**
367c0 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61   strings A, B, a
367d0 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  nd C:.**.** <ol>
367e0 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42  .** <li> If A==B
367f0 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c   then B==A..** <
36800 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20  li> If A==B and 
36810 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a  B==C then A==C..
36820 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b  ** <li> If A&lt;
36830 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a  B THEN B&gt;A..*
36840 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
36850 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e   and B&lt;C then
36860 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c   A&lt;C..** </ol
36870 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c  >.**.** If a col
36880 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
36890 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65  fails any of the
368a0 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e   above constrain
368b0 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63  ts and that.** c
368c0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
368d0 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64  n is  registered
368e0 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20   and used, then 
368f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
36900 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64  SQLite.** is und
36910 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
36920 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
36930 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
36940 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
36950 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36960 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74  tion().** with t
36970 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  he addition that
36980 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61   the xDestroy ca
36990 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
369a0 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a  d on pArg when.*
369b0 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * the collating 
369c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65  function is dele
369d0 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  ted..** ^Collati
369e0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
369f0 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68   deleted when th
36a00 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65  ey are overridde
36a10 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61  n by later.** ca
36a20 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  lls to the colla
36a30 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
36a40 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20  nctions or when 
36a50 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
36a60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
36a70 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
36a80 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
36a90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74  **.** ^The xDest
36aa0 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
36ab0 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65  <u>not</u> calle
36ac0 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c  d if the .** sql
36ad0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36ae0 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74  ation_v2() funct
36af0 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c  ion fails.  Appl
36b00 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e  ications that in
36b10 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
36b20 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36b30 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e  _v2() with a non
36b40 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61  -NULL xDestroy a
36b50 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a  rgument should .
36b60 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ** check the ret
36b70 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73  urn code and dis
36b80 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c  pose of the appl
36b90 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
36ba0 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76  nter.** themselv
36bb0 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65  es rather than e
36bc0 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20  xpecting SQLite 
36bd0 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20  to deal with it 
36be0 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69  for them..** Thi
36bf0 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66  s is different f
36c00 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20  rom every other 
36c10 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
36c20 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74  .  The inconsist
36c30 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f  ency .** is unfo
36c40 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e  rtunate but cann
36c50 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69  ot be changed wi
36c60 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62  thout breaking b
36c70 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d  ackwards .** com
36c80 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
36c90 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71  * See also:  [sq
36ca0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
36cb0 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73  needed()] and [s
36cc0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
36cd0 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f  _needed16()]..*/
36ce0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
36cf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36d00 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
36d10 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
36d20 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
36d30 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
36d40 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
36d50 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
36d60 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36d70 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36d80 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  d*).);.SQLITE_AP
36d90 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
36da0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
36db0 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
36dc0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
36dd0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
36de0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
36df0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
36e00 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
36e10 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
36e20 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
36e30 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
36e40 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  void*).);.SQLITE
36e50 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
36e60 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36e70 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  n16(.  sqlite3*,
36e80 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a   .  const void *
36e90 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65  zName,.  int eTe
36ea0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
36eb0 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
36ec0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
36ed0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
36ee0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
36ef0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36f00 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64  : Collation Need
36f10 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ed Callbacks.**.
36f20 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76  ** ^To avoid hav
36f30 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20  ing to register 
36f40 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  all collation se
36f50 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61  quences before a
36f60 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e   database.** can
36f70 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67   be used, a sing
36f80 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  le callback func
36f90 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
36fa0 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a  stered with the.
36fb0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
36fc0 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69  nection] to be i
36fd0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
36fe0 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  an undefined col
36ff0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
37000 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ce is required..
37010 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75  **.** ^If the fu
37020 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  nction is regist
37030 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
37040 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
37050 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a  _needed() API,.*
37060 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73  * then it is pas
37070 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  sed the names of
37080 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
37090 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61  tion sequences a
370a0 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63  s strings.** enc
370b0 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e  oded in UTF-8. ^
370c0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
370d0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
370e0 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20  is used,.** the 
370f0 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64  names are passed
37100 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
37110 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
37120 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63  e order..** ^A c
37130 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75  all to either fu
37140 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
37150 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c  the existing col
37160 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61  lation-needed ca
37170 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28  llback..**.** ^(
37180 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
37190 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  k is invoked, th
371a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
371b0 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70   passed is a cop
371c0 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f  y.** of the seco
371d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
371e0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
371f0 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20  _needed() or.** 
37200 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
37210 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54  n_needed16().  T
37220 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
37230 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61  nt is the databa
37240 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
37250 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
37260 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
37270 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
37280 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
37290 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
372a0 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74  TF16LE], indicat
372b0 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73  ing the most des
372c0 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74  irable form of t
372d0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
372e0 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f  sequence functio
372f0 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65  n required.  The
37300 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
37310 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
37320 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
37330 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
37340 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  nce.)^.**.** The
37350 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
37360 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74  on should regist
37370 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63  er the desired c
37380 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  ollation using.*
37390 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
373a0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20  e_collation()], 
373b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
373c0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20  collation16()], 
373d0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
373e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
373f0 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  v2()]..*/.SQLITE
37400 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
37410 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
37420 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  d(.  sqlite3*, .
37430 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64    void*, .  void
37440 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
37450 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
37460 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a  const char*).);.
37470 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
37480 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
37490 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
374a0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
374b0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
374c0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
374d0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
374e0 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53  d*).);..#ifdef S
374f0 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a  QLITE_HAS_CODEC.
37500 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
37510 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63  e key for an enc
37520 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e  rypted database.
37530 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73    This routine s
37540 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c  hould be.** call
37550 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73  ed right after s
37560 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a  qlite3_open()..*
37570 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
37580 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
37590 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
375a0 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
375b0 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
375c0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
375d0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
375e0 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
375f0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
37600 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
37610 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
37620 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
37630 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
37640 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
37650 79 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  y */.);.SQLITE_A
37660 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b  PI int sqlite3_k
37670 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  ey_v2(.  sqlite3
37680 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
37690 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
376a0 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
376b0 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  d */.  const cha
376c0 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20  r *zDbName,     
376d0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
376e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f   the database */
376f0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
37700 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
37710 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
37720 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65  );../*.** Change
37730 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f   the key on an o
37740 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49  pen database.  I
37750 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  f the current da
37760 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a  tabase is not.**
37770 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73   encrypted, this
37780 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e   routine will en
37790 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e  crypt it.  If pN
377a0 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30  ew==0 or nNew==0
377b0 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  , the.** databas
377c0 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a  e is decrypted..
377d0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
377e0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
377f0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
37800 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
37810 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
37820 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
37830 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
37840 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c  te3_rekey(.  sql
37850 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
37860 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
37870 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
37880 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
37890 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
378a0 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
378b0 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 53   new key */.);.S
378c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
378d0 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76 32 28 0a  lite3_rekey_v2(.
378e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
378f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37900 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
37910 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
37920 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
37930 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f  ame,           /
37940 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  * Name of the da
37950 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
37960 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
37970 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
37980 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
37990 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
379a0 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
379b0 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61  y for a SEE data
379c0 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
379d0 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
379e0 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75  e of the SEE rou
379f0 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
37a00 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
37a10 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69  oid sqlite3_acti
37a20 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73  vate_see(.  cons
37a30 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
37a40 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
37a50 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
37a60 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69  */.);.#endif..#i
37a70 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42  fdef SQLITE_ENAB
37a80 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53  LE_CEROD./*.** S
37a90 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
37aa0 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
37ab0 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20  CEROD database. 
37ac0 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
37ad0 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
37ae0 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65  he CEROD routine
37af0 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
37b00 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
37b10 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
37b20 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20  _cerod(.  const 
37b30 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
37b40 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
37b50 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
37b60 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .);.#endif../*.*
37b70 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70  * CAPI3REF: Susp
37b80 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
37b90 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a  r A Short Time.*
37ba0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
37bb0 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
37bc0 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
37bd0 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
37be0 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
37bf0 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
37c00 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
37c10 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
37c20 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
37c30 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
37c40 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
37c50 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
37c60 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
37c70 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c  sts with.** mill
37c80 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
37c90 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
37ca0 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
37cb0 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20  ounded up to.** 
37cc0 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
37cd0 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
37ce0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
37cf0 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
37d00 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
37d10 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
37d20 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
37d30 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ned..**.** ^SQLi
37d40 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
37d50 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
37d60 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
37d70 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
37d80 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
37d90 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
37da0 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65  ct.  If the xSle
37db0 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  ep() method.** o
37dc0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
37dd0 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  S is not impleme
37de0 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20  nted correctly, 
37df0 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  or not implement
37e00 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68  ed at.** all, th
37e10 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
37e20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  of sqlite3_sleep
37e30 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66  () may deviate f
37e40 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74  rom the descript
37e50 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72  ion.** in the pr
37e60 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
37e70 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
37e80 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65   int sqlite3_sle
37e90 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
37ea0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
37eb0 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
37ec0 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46  ding Temporary F
37ed0 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  iles.**.** ^(If 
37ee0 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
37ef0 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
37f00 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
37f10 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
37f20 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
37f30 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
37f40 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
37f50 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a  temporary files.
37f60 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51  ** created by SQ
37f70 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20  Lite when using 
37f80 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69  a built-in [sqli
37f90 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a  te3_vfs | VFS].*
37fa0 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  * will be placed
37fb0 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
37fc0 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20  ry.)^  ^If this 
37fd0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61  variable.** is a
37fe0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
37ff0 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f  hen SQLite perfo
38000 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72  rms a search for
38010 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a   an appropriate.
38020 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
38030 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  e directory..**.
38040 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
38050 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
38060 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
38070 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e in more than o
38080 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20  ne.** thread at 
38090 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e  a time.  It is n
380a0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
380b0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
380c0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20  ariable.** if a 
380d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
380e0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75  tion] is being u
380f0 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20  sed at the same 
38100 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61  time in a separa
38110 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a  te.** thread..**
38120 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
38130 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
38140 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
38150 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
38160 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
38170 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
38180 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
38190 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
381a0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
381b0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76   and that this v
381c0 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75  ariable remain u
381d0 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72  nchanged.** ther
381e0 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eafter..**.** ^T
381f0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
38200 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
38210 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73   may modify this
38220 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61   variable and ca
38230 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69  use.** it to poi
38240 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
38250 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
38260 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46  te3_malloc].  ^F
38270 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74  urthermore,.** t
38280 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
38290 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
382a0 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20   always assumes 
382b0 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a  that any string.
382c0 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ** that this var
382d0 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  iable points to 
382e0 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  is held in memor
382f0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
38300 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
38310 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61  loc] and the pra
38320 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20  gma may attempt 
38330 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d  to free that mem
38340 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ory.** using [sq
38350 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20  lite3_free]..** 
38360 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76  Hence, if this v
38370 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66  ariable is modif
38380 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69  ied directly, ei
38390 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62  ther it should b
383a0 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f  e.** made NULL o
383b0 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  r made to point 
383c0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
383d0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
383e0 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65  _malloc].** or e
383f0 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  lse the use of t
38400 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
38410 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
38420 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64   should be avoid
38430 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
38440 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e  e to Windows Run
38450 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20  time users:</b> 
38460 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64   The temporary d
38470 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65  irectory must be
38480 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f   set.** prior to
38490 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
384a0 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69  3_open] or [sqli
384b0 74 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f  te3_open_v2].  O
384c0 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75  therwise, variou
384d0 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68  s.** features th
384e0 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75  at require the u
384f0 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20  se of temporary 
38500 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 20  files may fail. 
38510 20 48 65 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65   Here is an.** e
38520 78 61 6d 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f  xample of how to
38530 20 64 6f 20 74 68 69 73 20 75 73 69 6e 67 20 43   do this using C
38540 2b 2b 20 77 69 74 68 20 74 68 65 20 57 69 6e 64  ++ with the Wind
38550 6f 77 73 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a  ows Runtime:.**.
38560 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
38570 70 72 65 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20  pre>.** LPCWSTR 
38580 7a 50 61 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a  zPath = Windows:
38590 3a 53 74 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63  :Storage::Applic
385a0 61 74 69 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65  ationData::Curre
385b0 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  nt->.** &nbsp;  
385c0 20 20 20 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64     TemporaryFold
385d0 65 72 2d 3e 50 61 74 68 2d 3e 44 61 74 61 28 29  er->Path->Data()
385e0 3b 0a 2a 2a 20 63 68 61 72 20 7a 50 61 74 68 42  ;.** char zPathB
385f0 75 66 26 23 39 31 3b 4d 41 58 5f 50 41 54 48 20  uf&#91;MAX_PATH 
38600 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d  + 1&#93;;.** mem
38610 73 65 74 28 7a 50 61 74 68 42 75 66 2c 20 30 2c  set(zPathBuf, 0,
38620 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42 75 66   sizeof(zPathBuf
38630 29 29 3b 0a 2a 2a 20 57 69 64 65 43 68 61 72 54  ));.** WideCharT
38640 6f 4d 75 6c 74 69 42 79 74 65 28 43 50 5f 55 54  oMultiByte(CP_UT
38650 46 38 2c 20 30 2c 20 7a 50 61 74 68 2c 20 2d 31  F8, 0, zPath, -1
38660 2c 20 7a 50 61 74 68 42 75 66 2c 20 73 69 7a 65  , zPathBuf, size
38670 6f 66 28 7a 50 61 74 68 42 75 66 29 2c 0a 2a 2a  of(zPathBuf),.**
38680 20 26 6e 62 73 70 3b 20 20 20 20 20 4e 55 4c 4c   &nbsp;     NULL
38690 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69  , NULL);.** sqli
386a0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
386b0 72 79 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  ry = sqlite3_mpr
386c0 69 6e 74 66 28 22 25 73 22 2c 20 7a 50 61 74 68  intf("%s", zPath
386d0 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  Buf);.** </pre><
386e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a  /blockquote>.*/.
386f0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
38700 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73  E_EXTERN char *s
38710 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
38720 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
38730 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
38740 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
38750 6e 67 20 44 61 74 61 62 61 73 65 20 46 69 6c 65  ng Database File
38760 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69  s.**.** ^(If thi
38770 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
38780 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  e is made to poi
38790 6e 74 20 74 6f