System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 3aa96e9dc5fc71d7d0b3ec6f2dab1dcd476696ad:


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 32 22 0a 23 64 65 66 69 6e 65 20 53 51  .8.2".#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 32 0a 23 64 65 66  BER 3008002.#def
1050: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1060: 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 33 2d  E_ID      "2013-
1070: 31 31 2d 32 32 20 32 31 3a 33 32 3a 34 34 20 66  11-22 21:32:44 f
1080: 33 33 36 63 31 38 66 62 37 32 61 62 39 30 65 39  336c18fb72ab90e9
1090: 33 36 34 30 62 31 32 61 63 35 34 30 64 34 31 61  3640b12ac540d41a
10a0: 63 63 63 37 36 35 38 22 0a 0a 2f 2a 0a 2a 2a 20  ccc7658"../*.** 
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 41 42 4f 52 54  ine SQLITE_ABORT
5a10: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54     (SQLITE_ABORT
5a30: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5a40: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5a50: 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20  AINT_CHECK      
5a60: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5a70: 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AINT | (1<<8)).#
5a80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a90: 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48  NSTRAINT_COMMITH
5aa0: 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  OOK   (SQLITE_CO
5ab0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38  NSTRAINT | (2<<8
5ac0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5ad0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52  E_CONSTRAINT_FOR
5ae0: 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54  EIGNKEY   (SQLIT
5af0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5b00: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5b10: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b20: 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53  _FUNCTION     (S
5b30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b40: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
5b50: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5b60: 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20  AINT_NOTNULL    
5b70: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5b80: 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23  AINT | (5<<8)).#
5b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5ba0: 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59  NSTRAINT_PRIMARY
5bb0: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  KEY   (SQLITE_CO
5bc0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38  NSTRAINT | (6<<8
5bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5be0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49  E_CONSTRAINT_TRI
5bf0: 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 54  GGER      (SQLIT
5c00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5c10: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
5c20: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c30: 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 53  _UNIQUE       (S
5c40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c50: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
5c60: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c70: 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20  AINT_VTAB       
5c80: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5c90: 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23  AINT | (9<<8)).#
5ca0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5cb0: 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20  NSTRAINT_ROWID  
5cc0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5cd0: 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38  NSTRAINT |(10<<8
5ce0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5cf0: 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52  E_NOTICE_RECOVER
5d00: 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54  _WAL      (SQLIT
5d10: 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38  E_NOTICE | (1<<8
5d20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d30: 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52  E_NOTICE_RECOVER
5d40: 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54  _ROLLBACK (SQLIT
5d50: 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38  E_NOTICE | (2<<8
5d60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d70: 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e  E_WARNING_AUTOIN
5d80: 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49 54  DEX       (SQLIT
5d90: 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c  E_WARNING | (1<<
5da0: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  8))../*.** CAPI3
5db0: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46  REF: Flags For F
5dc0: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69  ile Open Operati
5dd0: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
5de0: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69  bit values are i
5df0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
5e00: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61  in the.** 3rd pa
5e10: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
5e20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5e30: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
5e40: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70  .** in the 4th p
5e50: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
5e60: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
5e70: 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23  en] method..*/.#
5e80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5e90: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
5ea0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20      0x00000001  
5eb0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5ec0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5ed0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5ee0: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
5ef0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20      0x00000002  
5f00: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5f10: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5f20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5f30: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
5f40: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20      0x00000004  
5f50: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5f60: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5f70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5f80: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
5f90: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20      0x00000008  
5fa0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
5fb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5fc0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
5fd0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20      0x00000010  
5fe0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
5ff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6000: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20  EN_AUTOPROXY    
6010: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20      0x00000020  
6020: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6040: 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  EN_URI          
6050: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20      0x00000040  
6060: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6070: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6090: 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20  EN_MEMORY       
60a0: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20      0x00000080  
60b0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
60c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
60d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
60e0: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
60f0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20      0x00000100  
6100: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6120: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
6130: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20      0x00000200  
6140: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6160: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
6170: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20      0x00000400  
6180: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
61a0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
61b0: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20      0x00000800  
61c0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
61d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
61e0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
61f0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20      0x00001000  
6200: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6220: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
6230: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20      0x00002000  
6240: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6260: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
6270: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20  L   0x00004000  
6280: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6290: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62a0: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20  EN_NOMUTEX      
62b0: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20      0x00008000  
62c0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
62d0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
62e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62f0: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20  EN_FULLMUTEX    
6300: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20      0x00010000  
6310: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6320: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6340: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  EN_SHAREDCACHE  
6350: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20      0x00020000  
6360: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6370: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6390: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
63a0: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20      0x00040000  
63b0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
63c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
63d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
63e0: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  EN_WAL          
63f0: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20      0x00080000  
6400: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a  /* VFS only */..
6410: 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20  /* Reserved:    
6420: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6430: 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20       0x00F00000 
6440: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
6450: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61  EF: Device Chara
6460: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  cteristics.**.**
6470: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
6480: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
6490: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
64a0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
64b0: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
64c0: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
64d0: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
64e0: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61   these.** bit va
64f0: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20  lues expressing 
6500: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74  I/O characterist
6510: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20  ics of the mass 
6520: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63  storage.** devic
6530: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65  e that holds the
6540: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b   file that the [
6550: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6560: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f  ds].** refers to
6570: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
6580: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
6590: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
65a0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
65b0: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
65c0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
65d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
65e0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
65f0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
6600: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
6610: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
6620: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
6630: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
6640: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
6650: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
6660: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
6670: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6680: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6690: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
66a0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
66b0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
66c0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
66d0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
66e0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
66f0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
6700: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
6710: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
6720: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
6730: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6740: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
6750: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6760: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
6770: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
6780: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
6790: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
67a0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20  * to xWrite().  
67b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
67c0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
67d0: 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65  RITE property me
67e0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65  ans that.** afte
67f0: 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69  r reboot followi
6800: 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f  ng a crash or po
6810: 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e  wer loss, the on
6820: 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a  ly bytes in a.**
6830: 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20   file that were 
6840: 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61  written at the a
6850: 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c  pplication level
6860: 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e   might have chan
6870: 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ged.** and that 
6880: 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20  adjacent bytes, 
6890: 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69  even bytes withi
68a0: 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f  n the same secto
68b0: 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74  r are.** guarant
68c0: 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e  eed to be unchan
68d0: 67 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ged..*/.#define 
68e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
68f0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
6900: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
6910: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6920: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
6930: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6940: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6950: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6960: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
6970: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
6980: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6990: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
69a0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
69b0: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
69c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
69d0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
69e0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
69f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6a00: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
6a10: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
6a20: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6a30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6a40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6a50: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
6a60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6a70: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
6a80: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
6a90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6aa0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
6ab0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6ac0: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
6ad0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6ae0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
6af0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
6b00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6b10: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
6b20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6b30: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
6b40: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6b50: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
6b60: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
6b70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6b80: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6b90: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
6ba0: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
6bb0: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67  EF: File Locking
6bc0: 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51   Levels.**.** SQ
6bd0: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
6be0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
6bf0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
6c00: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
6c10: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
6c20: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
6c30: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
6c40: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
6c50: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6c60: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
6c70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6c80: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
6c90: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
6ca0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
6cb0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
6cc0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
6cd0: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
6ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6cf0: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
6d00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6d10: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
6d20: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
6d30: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
6d40: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a  tion Type Flags.
6d50: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74  **.** When SQLit
6d60: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
6d70: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  ync() method of 
6d80: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
6d90: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
6da0: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62  t it uses a comb
6db0: 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68  ination of.** th
6dc0: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
6dd0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
6de0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
6df0: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   When the SQLITE
6e00: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66  _SYNC_DATAONLY f
6e10: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20  lag is used, it 
6e20: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a  means that the.*
6e30: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  * sync operation
6e40: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66   only needs to f
6e50: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73  lush data to mas
6e60: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64  s storage.  Inod
6e70: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
6e80: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75   need not be flu
6e90: 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77  shed. If the low
6ea0: 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20  er four bits of 
6eb0: 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61  the flag.** equa
6ec0: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  l SQLITE_SYNC_NO
6ed0: 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  RMAL, that means
6ee0: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66   to use normal f
6ef0: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73  sync() semantics
6f00: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65  ..** If the lowe
6f10: 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61  r four bits equa
6f20: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  l SQLITE_SYNC_FU
6f30: 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  LL, that means.*
6f40: 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20  * to use Mac OS 
6f50: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
6f60: 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e   instead of fsyn
6f70: 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f  c()..**.** Do no
6f80: 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51  t confuse the SQ
6f90: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6fa0: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
6fb0: 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77  _FULL flags.** w
6fc0: 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20  ith the [PRAGMA 
6fd0: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52  synchronous]=NOR
6fe0: 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  MAL and [PRAGMA 
6ff0: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c  synchronous]=FUL
7000: 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20  L.** settings.  
7010: 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73  The [synchronous
7020: 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69   pragma] determi
7030: 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74  nes when calls t
7040: 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56  o the.** xSync V
7050: 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20  FS method occur 
7060: 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66  and applies unif
7070: 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c  ormly across all
7080: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54   platforms..** T
7090: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
70a0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
70b0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
70c0: 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a   determine how.*
70d0: 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72  * energetic or r
70e0: 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65  igorous or force
70f0: 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65  ful the sync ope
7100: 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a  rations are and.
7110: 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64  ** only make a d
7120: 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63  ifference on Mac
7130: 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66   OSX for the def
7140: 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65  ault SQLite code
7150: 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74  ..** (Third-part
7160: 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  y VFS implementa
7170: 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f  tions might also
7180: 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
7190: 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e  ction.** between
71a0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
71b0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
71c0: 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d  YNC_FULL, but am
71d0: 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61  ong the.** opera
71e0: 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74  ting systems nat
71f0: 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20  ively supported 
7200: 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20  by SQLite, only 
7210: 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73  Mac OSX.** cares
7220: 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65   about the diffe
7230: 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69  rence.).*/.#defi
7240: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  ne SQLITE_SYNC_N
7250: 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30  ORMAL        0x0
7260: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
7270: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20  ITE_SYNC_FULL   
7280: 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23         0x00003.#
7290: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
72a0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20  NC_DATAONLY     
72b0: 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20   0x00010../*.** 
72c0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
72d0: 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65  erface Open File
72e0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e   Handle.**.** An
72f0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7300: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
7310: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
7320: 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  n the .** [sqlit
7330: 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65  e3_vfs | OS inte
7340: 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49  rface layer].  I
7350: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74  ndividual OS int
7360: 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d  erface.** implem
7370: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a  entations will.*
7380: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61  * want to subcla
7390: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62  ss this object b
73a0: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69  y appending addi
73b0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
73c0: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75   for their own u
73d0: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64  se.  The pMethod
73e0: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69  s entry is a poi
73f0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
7400: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7410: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
7420: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66  efines methods f
7430: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a  or performing.**
7440: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
7450: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  on the open file
7460: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
7470: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
7480: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73   sqlite3_file;.s
7490: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
74a0: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72  le {.  const str
74b0: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
74c0: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73  ethods *pMethods
74d0: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f  ;  /* Methods fo
74e0: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a  r an open file *
74f0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
7500: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
7510: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20  ce File Virtual 
7520: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a  Methods Object.*
7530: 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20  *.** Every file 
7540: 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73  opened by the [s
7550: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7560: 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74  ] method populat
7570: 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  es an.** [sqlite
7580: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28  3_file] object (
7590: 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c  or, more commonl
75a0: 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66  y, a subclass of
75b0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
75c0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77  _file] object) w
75d0: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ith a pointer to
75e0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
75f0: 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  this object..** 
7600: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  This object defi
7610: 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20  nes the methods 
7620: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20  used to perform 
7630: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f  various operatio
7640: 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68  ns.** against th
7650: 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72  e open file repr
7660: 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b  esented by the [
7670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7680: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ject..**.** If t
7690: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
76a0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65  xOpen] method se
76b0: 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  ts the sqlite3_f
76c0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
76d0: 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f  ment .** to a no
76e0: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
76f0: 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
7700: 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f  _io_methods.xClo
7710: 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79  se method.** may
7720: 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e   be invoked even
7730: 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   if the [sqlite3
7740: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f  _vfs.xOpen] repo
7750: 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69  rted that it fai
7760: 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c  led.  The.** onl
7770: 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74  y way to prevent
7780: 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73   a call to xClos
7790: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  e following a fa
77a0: 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66  iled [sqlite3_vf
77b0: 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66  s.xOpen].** is f
77c0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
77d0: 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65  vfs.xOpen] to se
77e0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
77f0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
7800: 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a  ent.** to NULL..
7810: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
7820: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e  argument to xSyn
7830: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  c may be one of 
7840: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52  [SQLITE_SYNC_NOR
7850: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  MAL] or.** [SQLI
7860: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20  TE_SYNC_FULL].  
7870: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65  The first choice
7880: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66   is the normal f
7890: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73  sync()..** The s
78a0: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20  econd choice is 
78b0: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  a Mac OS X style
78c0: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20   fullsync.  The 
78d0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54  [SQLITE_SYNC_DAT
78e0: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d  AONLY].** flag m
78f0: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f  ay be ORed in to
7900: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
7910: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
7920: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20  the file.** and 
7930: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65  not its inode ne
7940: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64  eds to be synced
7950: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ..**.** The inte
7960: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
7970: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
7980: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
7990: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
79a0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
79b0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
79c0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
79d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
79e0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
79f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7a00: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
7a10: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
7a20: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
7a30: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
7a40: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
7a50: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
7a60: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
7a70: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65  the lock..** The
7a80: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c   xCheckReservedL
7a90: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65  ock() method che
7aa0: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20  cks whether any 
7ab0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
7ac0: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69  ion,.** either i
7ad0: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f  n this process o
7ae0: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
7af0: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
7b00: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a  ing a RESERVED,.
7b10: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
7b20: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
7b30: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
7b40: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
7b50: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
7b60: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f  ists and false o
7b70: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
7b80: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  The xFileControl
7b90: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67  () method is a g
7ba0: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65  eneric interface
7bb0: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73   that allows cus
7bc0: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65  tom.** VFS imple
7bd0: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69  mentations to di
7be0: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61  rectly control a
7bf0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e  n open file usin
7c00: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
7c10: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
7c20: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  ] interface.  Th
7c30: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72  e second "op" ar
7c40: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20  gument is an.** 
7c50: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20  integer opcode. 
7c60: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
7c70: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63  ent is a generic
7c80: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65   pointer intende
7c90: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  d to.** point to
7ca0: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
7cb0: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72  t may contain ar
7cc0: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65  guments or space
7cd0: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20   in which to.** 
7ce0: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c  write return val
7cf0: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20  ues.  Potential 
7d00: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f  uses for xFileCo
7d10: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65  ntrol() might be
7d20: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  .** functions to
7d30: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67   enable blocking
7d40: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65   locks with time
7d50: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20  outs, to change 
7d60: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73  the.** locking s
7d70: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61  trategy (for exa
7d80: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d  mple to use dot-
7d90: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20  file locks), to 
7da0: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74  inquire.** about
7db0: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61   the status of a
7dc0: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65   lock, or to bre
7dd0: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20  ak stale locks. 
7de0: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63   The SQLite.** c
7df0: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c  ore reserves all
7e00: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68   opcodes less th
7e10: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f  an 100 for its o
7e20: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51  wn use..** A [SQ
7e30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
7e40: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
7e50: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
7e60: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
7e70: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
7e80: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
7e90: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
7ea0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
7eb0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
7ec0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
7ed0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
7ee0: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70  flicts.  VFS imp
7ef0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
7f00: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
7f10: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20  QLITE_NOTFOUND] 
7f20: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  for file control
7f30: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68   opcodes that th
7f40: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63  ey do not.** rec
7f50: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ognize..**.** Th
7f60: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
7f70: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
7f80: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
7f90: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
7fa0: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
7fb0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
7fc0: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
7fd0: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
7fe0: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
7ff0: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
8000: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
8010: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
8020: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
8030: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8040: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
8050: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
8060: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
8070: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
8080: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
8090: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
80a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
80b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
80c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
80d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
80e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
80f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
8100: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8110: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
8120: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8130: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
8140: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8150: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
8160: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8170: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
8180: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8190: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
81a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
81b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
81c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
81d0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
81e0: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
81f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8200: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
8210: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
8220: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
8230: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8240: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
8250: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
8260: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8270: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8280: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
8290: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
82a0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
82b0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
82c0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
82d0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
82e0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
82f0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
8300: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
8310: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8320: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
8330: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
8340: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
8350: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8360: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
8370: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8380: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
8390: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
83a0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
83b0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
83c0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
83d0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
83e0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
83f0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8400: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
8410: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
8420: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
8430: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
8440: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
8450: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
8460: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
8470: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
8480: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
8490: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
84a0: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
84b0: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
84c0: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
84d0: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
84e0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
84f0: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
8500: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
8510: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
8520: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8530: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
8540: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
8550: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
8560: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
8570: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8580: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
8590: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
85a0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
85b0: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
85c0: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
85d0: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
85e0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
85f0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
8600: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
8610: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8620: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8630: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
8640: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
8650: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
8660: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8670: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8680: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
8690: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
86a0: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
86b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
86c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
86d0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
86e0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
86f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8700: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
8710: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
8720: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8730: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8740: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
8750: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8760: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
8770: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
8780: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
8790: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
87a0: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
87b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
87c0: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
87d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
87e0: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
87f0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8800: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8810: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
8820: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
8830: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
8840: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
8850: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
8860: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
8870: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
8880: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
8890: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
88a0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
88b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
88c0: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
88d0: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
88e0: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
88f0: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
8900: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
8910: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
8920: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
8930: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
8940: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8950: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8960: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
8970: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
8980: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8990: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
89a0: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
89b0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
89c0: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
89d0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
89e0: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
89f0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8a00: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8a10: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
8a20: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
8a30: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
8a40: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
8a50: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
8a60: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
8a70: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
8a80: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a  rol Opcodes.**.*
8a90: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
8aa0: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70  constants are op
8ab0: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46  codes for the xF
8ac0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
8ad0: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  d.** of the [sql
8ae0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
8af0: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20   object and for 
8b00: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8b10: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20  e_control()].** 
8b20: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
8b30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8b40: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
8b50: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
8b60: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
8b70: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
8b80: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
8b90: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
8ba0: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
8bb0: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
8bc0: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
8bd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
8be0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8bf0: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
8c00: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
8c10: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
8c20: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
8c30: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
8c40: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
8c50: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
8c60: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
8c70: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
8c80: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
8c90: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
8ca0: 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65  ing and only nee
8cb0: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ds to be support
8cc0: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54  ed when SQLITE_T
8cd0: 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65  EST.** is define
8ce0: 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  d..** <ul>.** <l
8cf0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8d00: 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20  _SIZE_HINT]].** 
8d10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8d20: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63  L_SIZE_HINT] opc
8d30: 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53  ode is used by S
8d40: 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68  QLite to give th
8d50: 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61  e VFS.** layer a
8d60: 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72   hint of how lar
8d70: 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
8d80: 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74  file will grow t
8d90: 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a  o be during the.
8da0: 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73  ** current trans
8db0: 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69  action.  This hi
8dc0: 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e  nt is not guaran
8dd0: 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72  teed to be accur
8de0: 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73  ate but it.** is
8df0: 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54   often close.  T
8e00: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46  he underlying VF
8e10: 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74  S might choose t
8e20: 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61  o preallocate da
8e30: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73  tabase.** file s
8e40: 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68  pace based on th
8e50: 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72  is hint in order
8e60: 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20   to help writes 
8e70: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
8e80: 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74  ** file run fast
8e90: 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  er..**.** <li>[[
8ea0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
8eb0: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  NK_SIZE]].** The
8ec0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
8ed0: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64  HUNK_SIZE] opcod
8ee0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71  e is used to req
8ef0: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46  uest that the VF
8f00: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64  S.** extends and
8f10: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64   truncates the d
8f20: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20  atabase file in 
8f30: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65  chunks of a size
8f40: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
8f50: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66   the user. The f
8f60: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
8f70: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  o [sqlite3_file_
8f80: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c  control()] shoul
8f90: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  d .** point to a
8fa0: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20  n integer (type 
8fb0: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  int) containing 
8fc0: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69  the new chunk-si
8fd0: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72  ze to use.** for
8fe0: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64   the nominated d
8ff0: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74  atabase. Allocat
9000: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c  ing database fil
9010: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65  e space in large
9020: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20  .** chunks (say 
9030: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20  1MB at a time), 
9040: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d  may reduce file-
9050: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61  system fragmenta
9060: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72  tion and.** impr
9070: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
9080: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e  on some systems.
9090: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
90a0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
90b0: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
90c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
90d0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  LE_POINTER] opco
90e0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
90f0: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
9100: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
9110: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
9120: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
9130: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9140: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9150: 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71  on.  See the [sq
9160: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9170: 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74  ol()] documentat
9180: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  ion for.** addit
9190: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
91a0: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
91b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
91c0: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28  _OMITTED]].** ^(
91d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
91e0: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20  L_SYNC_OMITTED] 
91f0: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9200: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9210: 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20  y.** SQLite and 
9220: 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65  sent to all VFSe
9230: 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20  s in place of a 
9240: 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e  call to the xSyn
9250: 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e  c method.** when
9260: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
9270: 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52  nnection has [PR
9280: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
9290: 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a  ] set to OFF.)^.
92a0: 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69  ** Some speciali
92b0: 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74  zed VFSes need t
92c0: 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72  his signal in or
92d0: 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63  der to operate c
92e0: 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e  orrectly.** when
92f0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
9300: 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79  nous | PRAGMA sy
9310: 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69  nchronous=OFF] i
9320: 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20  s set, but most 
9330: 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74  .** VFSes do not
9340: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9350: 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c  l and should sil
9360: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9370: 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70  s opcode..** App
9380: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
9390: 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74   not call [sqlit
93a0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
93b0: 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20  )] with this.** 
93c0: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
93d0: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74  so may disrupt t
93e0: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
93f0: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9400: 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f  VFSes.** that do
9410: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9420: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9430: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9440: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
9450: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
9460: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
9470: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9480: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
9490: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
94a0: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
94b0: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
94c0: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
94d0: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
94e0: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
94f0: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
9500: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
9510: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
9520: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
9530: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
9540: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
9550: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
9560: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
9570: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
9580: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
9590: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
95a0: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
95b0: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
95c0: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
95d0: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
95e0: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
95f0: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
9600: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
9610: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
9620: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
9630: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
9640: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
9650: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
9660: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
9670: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
9680: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
9690: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
96a0: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
96b0: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
96c0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
96d0: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
96e0: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
96f0: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
9700: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
9710: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
9720: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
9730: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
9740: 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74  er i the new ret
9750: 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65  ry count and the
9760: 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67   second.** integ
9770: 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e  er is the delay.
9780: 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65    If either inte
9790: 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ger is negative,
97a0: 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e   then the settin
97b0: 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  g.** is not chan
97c0: 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20  ged but instead 
97d0: 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
97e0: 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20  of that setting 
97f0: 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e  is written.** in
9800: 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74  to the array ent
9810: 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65  ry, allowing the
9820: 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73   current retry s
9830: 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a  ettings to be.**
9840: 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
9850: 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61  The zDbName para
9860: 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64  meter is ignored
9870: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9880: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
9890: 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65  ST_WAL]].** ^The
98a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
98b0: 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f  ERSIST_WAL] opco
98c0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
98d0: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
98e0: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41  * persistent [WA
98f0: 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20  L | Write Ahead 
9900: 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42  Log] setting.  B
9910: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61  y default, the a
9920: 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74  uxiliary.** writ
9930: 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20  e ahead log and 
9940: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
9950: 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61  les used for tra
9960: 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
9970: 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69  .** are automati
9980: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68  cally deleted wh
9990: 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f  en the latest co
99a0: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20  nnection to the 
99b0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73  database.** clos
99c0: 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72  es.  Setting per
99d0: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
99e0: 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69   causes those fi
99f0: 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61  les to persist a
9a00: 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20  fter.** close.  
9a10: 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66  Persisting the f
9a20: 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77  iles is useful w
9a30: 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73  hen other proces
9a40: 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a  ses that do not.
9a50: 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65  ** have write pe
9a60: 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20  rmission on the 
9a70: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69  directory contai
9a80: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
9a90: 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74  e file want.** t
9aa0: 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62  o read the datab
9ab0: 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65  ase file, as the
9ac0: 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20   WAL and shared 
9ad0: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73  memory files mus
9ae0: 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72  t exist.** in or
9af0: 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  der for the data
9b00: 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61  base to be reada
9b10: 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68  ble.  The fourth
9b20: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
9b30: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9b40: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
9b50: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
9b60: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
9b70: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
9b80: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
9b90: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72  0 to disable per
9ba0: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
9bb0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
9bc0: 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41  persistent.** WA
9bd0: 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  L mode.  If the 
9be0: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
9bf0: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
9c00: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
9c10: 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65  urrent.** WAL pe
9c20: 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e  rsistence settin
9c30: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
9c40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
9c50: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
9c60: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9c70: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
9c80: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  E_OVERWRITE] opc
9c90: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
9ca0: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
9cb0: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70  ** persistent "p
9cc0: 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69  owersafe-overwri
9cd0: 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65  te" or "PSOW" se
9ce0: 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57  tting.  The PSOW
9cf0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65   setting.** dete
9d00: 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49  rmines the [SQLI
9d10: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
9d20: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69  FE_OVERWRITE] bi
9d30: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76  t of the.** xDev
9d40: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
9d50: 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20  cs methods. The 
9d60: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
9d70: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
9d80: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9d90: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
9da0: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
9db0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
9dc0: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
9dd0: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
9de0: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  le zero-damage m
9df0: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
9e00: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a  le zero-damage.*
9e10: 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  * mode.  If the 
9e20: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
9e30: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
9e40: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
9e50: 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64  urrent.** zero-d
9e60: 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69  amage mode setti
9e70: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
9e80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
9e90: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
9ea0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f   [SQLITE_FCNTL_O
9eb0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9ec0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   is invoked by S
9ed0: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e  QLite after open
9ee0: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74  ing.** a write t
9ef0: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e  ransaction to in
9f00: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c  dicate that, unl
9f10: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64  ess it is rolled
9f20: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a   back for some.*
9f30: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e  * reason, the en
9f40: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69  tire database fi
9f50: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77  le will be overw
9f60: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75  ritten by the cu
9f70: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61  rrent .** transa
9f80: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75  ction. This is u
9f90: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70  sed by VACUUM op
9fa0: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
9fb0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9fc0: 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20  TL_VFSNAME]].** 
9fd0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9fe0: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f  TL_VFSNAME] opco
9ff0: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
a000: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d  o obtain the nam
a010: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46  es of.** all [VF
a020: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20  Ses] in the VFS 
a030: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65  stack.  The name
a040: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53  s are of all VFS
a050: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a   shims and the.*
a060: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c  * final bottom-l
a070: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69  evel VFS are wri
a080: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
a090: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
a0a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
a0b0: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65  oc()] and the re
a0c0: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69  sult is stored i
a0d0: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  n the char* vari
a0e0: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65  able.** that the
a0f0: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
a100: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69  r of [sqlite3_fi
a110: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f  le_control()] po
a120: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20  ints to..** The 
a130: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e  caller is respon
a140: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
a150: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65  g the memory whe
a160: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68  n done.  As with
a170: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e  .** all file-con
a180: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68  trol actions, th
a190: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e  ere is no guaran
a1a0: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69  tee that this wi
a1b0: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64  ll actually.** d
a1c0: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c  o anything.  Cal
a1d0: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74  lers should init
a1e0: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a  ialize the char*
a1f0: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e   variable to a N
a200: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ULL.** pointer i
a210: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65  n case this file
a220: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20  -control is not 
a230: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68  implemented.  Th
a240: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  is file-control.
a250: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ** is intended f
a260: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73  or diagnostic us
a270: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  e only..**.** <l
a280: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a290: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
a2a0: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
a2b0: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
a2c0: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
a2d0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a2e0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
a2f0: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
a300: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
a310: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
a320: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
a330: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
a340: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
a350: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
a360: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
a370: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
a380: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a390: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
a3a0: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
a3b0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
a3c0: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
a3d0: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
a3e0: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
a3f0: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
a400: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
a410: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
a420: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
a430: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
a440: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
a450: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
a460: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
a470: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
a480: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
a490: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a4a0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a4b0: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
a4c0: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
a4d0: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
a4e0: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
a4f0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
a500: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
a510: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
a520: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
a530: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
a540: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
a550: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
a560: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
a570: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
a580: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
a590: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
a5a0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
a5b0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a5c0: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
a5d0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
a5e0: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
a5f0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
a600: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
a610: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
a620: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a630: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
a640: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
a650: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
a660: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
a670: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
a680: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
a690: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
a6a0: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
a6b0: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
a6c0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
a6d0: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53  ent.  ^If the [S
a6e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a6f0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a700: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
a710: 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65  result code othe
a720: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
a730: 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f  K] or [SQLITE_NO
a740: 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65  TFOUND], that me
a750: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ans.** that the 
a760: 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  VFS encountered 
a770: 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68  an error while h
a780: 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41  andling the [PRA
a790: 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  GMA] and the.** 
a7a0: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74  compilation of t
a7b0: 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20  he PRAGMA fails 
a7c0: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
a7d0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a7e0: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
a7f0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72  le control occur
a800: 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69  s at the beginni
a810: 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61  ng of pragma sta
a820: 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20  tement analysis 
a830: 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20  and so.** it is 
a840: 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65  able to override
a850: 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d   built-in [PRAGM
a860: 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  A] statements..*
a870: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a880: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
a890: 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  LER]].** ^The [S
a8a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
a8b0: 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65  HANDLER].** file
a8c0: 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20  -control may be 
a8d0: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
a8e0: 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  e on the databas
a8f0: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a  e file handle.**
a900: 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69   shortly after i
a910: 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f  t is opened in o
a920: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
a930: 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74  a custom VFS wit
a940: 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74  h access.** to t
a950: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62  he connections b
a960: 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
a970: 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65  back. The argume
a980: 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76  nt is of type (v
a990: 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20  oid **).** - an 
a9a0: 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f  array of two (vo
a9b0: 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68  id *) values. Th
a9c0: 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29  e first (void *)
a9d0: 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73   actually points
a9e0: 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  .** to a functio
a9f0: 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28  n of type (int (
aa00: 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20  *)(void *)). In 
aa10: 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20  order to invoke 
aa20: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  the connections.
aa30: 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c  ** busy-handler,
aa40: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73   this function s
aa50: 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64  hould be invoked
aa60: 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64   with the second
aa70: 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20   (void *) in.** 
aa80: 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65  the array as the
aa90: 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20   only argument. 
aaa0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f  If it returns no
aab0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
aac0: 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68   operation.** sh
aad0: 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e  ould be retried.
aae0: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a   If it returns z
aaf0: 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20  ero, the custom 
ab00: 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64  VFS should aband
ab10: 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  on the.** curren
ab20: 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  t operation..**.
ab30: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ab40: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
ab50: 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61  ME]].** ^Applica
ab60: 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20  tion can invoke 
ab70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
ab80: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20  L_TEMPFILENAME] 
ab90: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
aba0: 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67  to have SQLite g
abb0: 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d  enerate a.** tem
abc0: 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20  porary filename 
abd0: 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61  using the same a
abe0: 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73  lgorithm that is
abf0: 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e   followed to gen
ac00: 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  erate.** tempora
ac10: 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72  ry filenames for
ac20: 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64   TEMP tables and
ac30: 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20   other internal 
ac40: 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72  uses.  The.** ar
ac50: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
ac60: 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20   a char** which 
ac70: 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77  will be filled w
ac80: 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ith the filename
ac90: 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  .** written into
aca0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
acb0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
acc0: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63  alloc()].  The c
acd0: 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20  aller should.** 
ace0: 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
acf0: 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72  free()] on the r
ad00: 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61  esult to avoid a
ad10: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a   memory leak..**
ad20: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
ad30: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
ad40: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
ad50: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
ad60: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
ad70: 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79  is used to query
ad80: 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d   or set the.** m
ad90: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
ada0: 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c   bytes that will
adb0: 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d   be used for mem
adc0: 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a  ory-mapped I/O..
add0: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
ade0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
adf0: 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20  a value of type 
ae00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68  sqlite3_int64 th
ae10: 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69  at.** is an advi
ae20: 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  sory maximum num
ae30: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
ae40: 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f  the file to memo
ae50: 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20  ry map.  The.** 
ae60: 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77  pointer is overw
ae70: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
ae80: 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20  old value.  The 
ae90: 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61  limit is not cha
aea0: 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76  nged if.** the v
aeb0: 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20  alue originally 
aec0: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65  pointed to is ne
aed0: 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74  gative, and so t
aee0: 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74  he current limit
aef0: 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72   .** can be quer
af00: 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69  ied by passing i
af10: 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  n a pointer to a
af20: 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
af30: 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d  .  This.** file-
af40: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
af50: 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d  internally to im
af60: 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20  plement [PRAGMA 
af70: 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a  mmap_size]..**.*
af80: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
af90: 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20  CNTL_TRACE]].** 
afa0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
afb0: 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f  L_TRACE] file co
afc0: 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61  ntrol provides a
afd0: 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74  dvisory informat
afe0: 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46  ion.** to the VF
aff0: 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65  S about what the
b000: 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f   higher layers o
b010: 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61  f the SQLite sta
b020: 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a  ck are doing..**
b030: 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   This file contr
b040: 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f  ol is used by so
b050: 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20  me VFS activity 
b060: 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e  tracing [shims].
b070: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
b080: 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   is a zero-termi
b090: 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48  nated string.  H
b0a0: 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20  igher layers in 
b0b0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74  the.** SQLite st
b0c0: 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65  ack may generate
b0d0: 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68   instances of th
b0e0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
b0f0: 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  if.** the [SQLIT
b100: 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43  E_USE_FCNTL_TRAC
b110: 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
b120: 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
b130: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  d..**.** </ul>.*
b140: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
b150: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
b160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
b170: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b180: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
b190: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a  E             2.
b1a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
b1b0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
b1c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
b1d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41  define SQLITE_LA
b1e0: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
b1f0: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#d
b200: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b210: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
b220: 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
b230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b240: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20  L_CHUNK_SIZE    
b250: 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
b260: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b270: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
b280: 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
b290: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b2a0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
b2b0: 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e          8.#defin
b2c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
b2d0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20  IN32_AV_RETRY   
b2e0: 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
b2f0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45   SQLITE_FCNTL_PE
b300: 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20  RSIST_WAL       
b310: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
b320: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
b330: 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  RWRITE          
b340: 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53      11.#define S
b350: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
b360: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20  AME             
b370: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51     12.#define SQ
b380: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
b390: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
b3a0: 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    13.#define SQL
b3b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b3c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b3d0: 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   14.#define SQLI
b3e0: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
b3f0: 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20  DLER            
b400: 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  15.#define SQLIT
b410: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
b420: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31  NAME           1
b430: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
b440: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
b450: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
b460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b470: 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20  FCNTL_TRACE     
b480: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a               19.
b490: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b4a0: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
b4b0: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
b4c0: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
b4d0: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
b4e0: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
b4f0: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
b500: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
b510: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
b520: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
b530: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
b540: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
b550: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
b560: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
b570: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
b580: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
b590: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
b5a0: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
b5b0: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
b5c0: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
b5d0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
b5e0: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
b5f0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
b600: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
b610: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
b620: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
b630: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
b640: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
b650: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
b660: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
b670: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
b680: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
b690: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
b6a0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
b6b0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
b6c0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
b6d0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
b6e0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
b6f0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
b700: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
b710: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
b720: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
b730: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
b740: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
b750: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
b760: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
b770: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
b780: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
b790: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
b7a0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
b7b0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
b7c0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
b7d0: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
b7e0: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
b7f0: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
b800: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
b810: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
b820: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
b830: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
b840: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
b850: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
b860: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
b870: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
b880: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
b890: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
b8a0: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
b8b0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
b8c0: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
b8d0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
b8e0: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
b8f0: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
b900: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
b910: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
b920: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
b930: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
b940: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
b950: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
b960: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
b970: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
b980: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
b990: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
b9a0: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
b9b0: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
b9c0: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
b9d0: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
b9e0: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
b9f0: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
ba00: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
ba10: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
ba20: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
ba30: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
ba40: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
ba50: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
ba60: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
ba70: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
ba80: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
ba90: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
baa0: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
bab0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
bac0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
bad0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
bae0: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
baf0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
bb00: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
bb10: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
bb20: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
bb30: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
bb40: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
bb50: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
bb60: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
bb70: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
bb80: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
bb90: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
bba0: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
bbb0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
bbc0: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
bbd0: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
bbe0: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
bbf0: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
bc00: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
bc10: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
bc20: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
bc30: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
bc40: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
bc50: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
bc60: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
bc70: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
bc80: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
bc90: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
bca0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
bcb0: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
bcc0: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
bcd0: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
bce0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
bcf0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
bd00: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
bd10: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
bd20: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
bd30: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
bd40: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
bd50: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
bd60: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
bd70: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
bd80: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
bd90: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
bda0: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
bdb0: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
bdc0: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
bdd0: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
bde0: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
bdf0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
be00: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
be10: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
be20: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
be30: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
be40: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
be50: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
be60: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
be70: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
be80: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
be90: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
bea0: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
beb0: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
bec0: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
bed0: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
bee0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
bef0: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
bf00: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
bf10: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
bf20: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
bf30: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
bf40: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
bf50: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
bf60: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
bf70: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
bf80: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
bf90: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
bfa0: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
bfb0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
bfc0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
bfd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
bfe0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
bff0: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
c000: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
c010: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
c020: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
c030: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
c040: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
c050: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
c060: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
c070: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
c080: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
c090: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
c0a0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
c0b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
c0c0: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
c0d0: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
c0e0: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
c0f0: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
c100: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
c110: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
c120: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
c130: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
c140: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
c150: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
c160: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
c170: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
c180: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
c190: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
c1a0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
c1b0: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
c1c0: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
c1d0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
c1e0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
c1f0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c200: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
c210: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c220: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
c230: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
c240: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
c250: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
c260: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
c270: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
c280: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c290: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
c2a0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c2b0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
c2c0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
c2d0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
c2e0: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
c2f0: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
c300: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
c310: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
c320: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
c330: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
c340: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
c350: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
c360: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
c370: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
c380: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
c390: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
c3a0: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
c3b0: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
c3c0: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
c3d0: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
c3e0: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
c3f0: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
c400: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
c410: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
c420: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
c430: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
c440: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
c450: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
c460: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
c470: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
c480: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
c490: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
c4a0: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
c4b0: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
c4c0: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
c4d0: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
c4e0: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
c4f0: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
c500: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
c510: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
c520: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
c530: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
c540: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
c550: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
c560: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
c570: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
c580: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
c590: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
c5a0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
c5b0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
c5c0: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
c5d0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
c5e0: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
c5f0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
c600: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
c610: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
c620: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
c630: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
c640: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
c650: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
c660: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
c670: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
c680: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
c690: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
c6a0: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
c6b0: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
c6c0: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
c6d0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
c6e0: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
c6f0: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
c700: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
c710: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
c720: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
c730: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
c740: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
c750: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
c760: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
c770: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
c780: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
c790: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
c7a0: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
c7b0: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
c7c0: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
c7d0: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
c7e0: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
c7f0: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
c800: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
c810: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
c820: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
c830: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
c840: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
c850: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
c860: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
c870: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
c880: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
c890: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
c8a0: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
c8b0: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
c8c0: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
c8d0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
c8e0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
c8f0: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
c900: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
c910: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
c920: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
c930: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
c940: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
c950: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
c960: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
c970: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
c980: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
c990: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
c9a0: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
c9b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
c9c0: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
c9d0: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
c9e0: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
c9f0: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
ca00: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
ca10: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
ca20: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
ca30: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
ca40: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
ca50: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
ca60: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
ca70: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
ca80: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
ca90: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
caa0: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
cab0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
cac0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
cad0: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
cae0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
caf0: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
cb00: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
cb10: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
cb20: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
cb30: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
cb40: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
cb50: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
cb60: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
cb70: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
cb80: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
cb90: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
cba0: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
cbb0: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
cbc0: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
cbd0: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
cbe0: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
cbf0: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
cc00: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
cc10: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
cc20: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
cc30: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
cc40: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
cc50: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
cc60: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
cc70: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
cc80: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
cc90: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
cca0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
ccb0: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
ccc0: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
ccd0: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
cce0: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
ccf0: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
cd00: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
cd10: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
cd20: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
cd30: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
cd40: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
cd50: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
cd60: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
cd70: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
cd80: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
cd90: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
cda0: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
cdb0: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
cdc0: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
cdd0: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
cde0: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
cdf0: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
ce00: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
ce10: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
ce20: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
ce30: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
ce40: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
ce50: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
ce60: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
ce70: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
ce80: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
ce90: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
cea0: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
ceb0: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
cec0: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
ced0: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
cee0: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
cef0: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
cf00: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
cf10: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
cf20: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
cf30: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
cf40: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
cf50: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
cf60: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
cf70: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
cf80: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
cf90: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
cfa0: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
cfb0: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
cfc0: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
cfd0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
cfe0: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
cff0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
d000: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
d010: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
d020: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
d030: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
d040: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
d050: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
d060: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
d070: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
d080: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
d090: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
d0a0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
d0b0: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
d0c0: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
d0d0: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
d0e0: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
d0f0: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
d100: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
d110: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
d120: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
d130: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
d140: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
d150: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
d160: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
d170: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
d180: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
d190: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
d1a0: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
d1b0: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
d1c0: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
d1d0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
d1e0: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
d1f0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
d200: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
d210: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
d220: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
d230: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
d240: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
d250: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
d260: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
d270: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
d280: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
d290: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
d2a0: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
d2b0: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
d2c0: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
d2d0: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
d2e0: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
d2f0: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
d300: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
d310: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
d320: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
d330: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
d340: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
d350: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
d360: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
d370: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
d380: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
d390: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
d3a0: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
d3b0: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
d3c0: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
d3d0: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
d3e0: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
d3f0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
d400: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
d410: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
d420: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
d430: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
d440: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
d450: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
d460: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
d470: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
d480: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
d490: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
d4a0: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
d4b0: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
d4c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
d4d0: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
d4e0: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
d4f0: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
d500: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
d510: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
d520: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
d530: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
d540: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
d550: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
d560: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
d570: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
d580: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
d590: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
d5a0: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
d5b0: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
d5c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
d5d0: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
d5e0: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
d5f0: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
d600: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
d610: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
d620: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
d630: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
d640: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
d650: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
d660: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
d670: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
d680: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
d690: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
d6a0: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
d6b0: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
d6c0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
d6d0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
d6e0: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
d6f0: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
d700: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
d710: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
d720: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
d730: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d740: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
d750: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
d760: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
d770: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d780: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
d790: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
d7a0: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
d7b0: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
d7c0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
d7d0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
d7e0: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
d7f0: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
d800: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d810: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
d820: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
d830: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
d840: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
d850: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
d860: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
d870: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
d880: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
d890: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
d8a0: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
d8b0: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
d8c0: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
d8d0: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
d8e0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
d8f0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
d900: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
d910: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
d920: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
d930: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
d940: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
d950: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d960: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
d970: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
d980: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
d990: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
d9a0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
d9b0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
d9c0: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
d9d0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
d9e0: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
d9f0: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
da00: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
da10: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
da20: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
da30: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
da40: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
da50: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
da60: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
da70: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
da80: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
da90: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
daa0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
dab0: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
dac0: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
dad0: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
dae0: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
daf0: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
db00: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
db10: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
db20: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
db30: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
db40: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
db50: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
db60: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
db70: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
db80: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
db90: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
dba0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
dbb0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
dbc0: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
dbd0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
dbe0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
dbf0: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
dc00: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
dc10: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
dc20: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
dc30: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
dc40: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
dc50: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
dc60: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
dc70: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
dc80: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
dc90: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
dca0: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
dcb0: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
dcc0: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
dcd0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
dce0: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
dcf0: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
dd00: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
dd10: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
dd20: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
dd30: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
dd40: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
dd50: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
dd60: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
dd70: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
dd80: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
dd90: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
dda0: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
ddb0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
ddc0: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
ddd0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
dde0: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
ddf0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
de00: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
de10: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
de20: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
de30: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
de40: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
de50: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
de60: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
de70: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
de80: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
de90: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
dea0: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
deb0: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
dec0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
ded0: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
dee0: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
def0: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
df00: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
df10: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
df20: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
df30: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
df40: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
df50: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
df60: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
df70: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
df80: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
df90: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
dfa0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
dfb0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
dfc0: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
dfd0: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
dfe0: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
dff0: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
e000: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
e010: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
e020: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
e030: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
e040: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
e050: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
e060: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
e070: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
e080: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
e090: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
e0a0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e0b0: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
e0c0: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
e0d0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
e0e0: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
e0f0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
e100: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
e110: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
e120: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
e130: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
e140: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
e150: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
e160: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
e170: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
e180: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
e190: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
e1a0: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
e1b0: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
e1c0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
e1d0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
e1e0: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
e1f0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
e200: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
e210: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
e220: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
e230: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
e240: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
e250: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
e260: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
e270: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
e280: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
e290: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
e2a0: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
e2b0: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
e2c0: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
e2d0: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
e2e0: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
e2f0: 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68   was given no th
e300: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
e310: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
e320: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
e330: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
e340: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
e350: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
e360: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
e370: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
e380: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
e390: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
e3a0: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
e3b0: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
e3c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e3d0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
e3e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e3f0: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
e400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e410: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
e420: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
e430: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
e440: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
e450: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
e460: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
e470: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
e480: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
e490: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
e4a0: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
e4b0: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
e4c0: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
e4d0: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
e4e0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
e4f0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
e500: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
e510: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
e520: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
e530: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
e540: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
e550: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
e560: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
e570: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
e580: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
e590: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
e5a0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
e5b0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
e5c0: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
e5d0: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
e5e0: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
e5f0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
e600: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
e610: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
e620: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
e630: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
e640: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
e650: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
e660: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
e670: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
e680: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
e690: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
e6a0: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
e6b0: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
e6c0: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
e6d0: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
e6e0: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
e6f0: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
e700: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
e710: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
e720: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
e730: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
e740: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
e750: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
e760: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
e770: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e780: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
e790: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
e7a0: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
e7b0: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
e7c0: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
e7d0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
e7e0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
e7f0: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
e800: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
e810: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
e820: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
e830: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
e840: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e850: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
e860: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
e870: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
e880: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
e890: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
e8a0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
e8b0: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
e8c0: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
e8d0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
e8e0: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
e8f0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e900: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
e910: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e920: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
e930: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
e940: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
e950: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
e960: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
e970: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
e980: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
e990: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e9a0: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
e9b0: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
e9c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
e9d0: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
e9e0: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
e9f0: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
ea00: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
ea10: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
ea20: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
ea30: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
ea40: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
ea50: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
ea60: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
ea70: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ea80: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
ea90: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
eaa0: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
eab0: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
eac0: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
ead0: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
eae0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
eaf0: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
eb00: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
eb10: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
eb20: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
eb30: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
eb40: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
eb50: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
eb60: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
eb70: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
eb80: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
eb90: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
eba0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
ebb0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
ebc0: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
ebd0: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
ebe0: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
ebf0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
ec00: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
ec10: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
ec20: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
ec30: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
ec40: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
ec50: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
ec60: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
ec70: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
ec80: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
ec90: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
eca0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
ecb0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
ecc0: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
ecd0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
ece0: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
ecf0: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
ed00: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
ed10: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
ed20: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
ed30: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
ed40: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
ed50: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
ed60: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
ed70: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
ed80: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ed90: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
eda0: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
edb0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
edc0: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
edd0: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
ede0: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
edf0: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
ee00: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
ee10: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
ee20: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
ee30: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
ee40: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
ee50: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
ee60: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
ee70: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
ee80: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
ee90: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
eea0: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
eeb0: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
eec0: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
eed0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
eee0: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
eef0: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
ef00: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
ef10: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
ef20: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
ef30: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
ef40: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
ef50: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
ef60: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
ef70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
ef80: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
ef90: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
efa0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
efb0: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
efc0: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
efd0: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
efe0: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
eff0: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
f000: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
f010: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
f020: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
f030: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
f040: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
f050: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
f060: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
f070: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
f080: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
f090: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
f0a0: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
f0b0: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
f0c0: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
f0d0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
f0e0: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
f0f0: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
f100: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
f110: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
f120: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
f130: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
f140: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
f150: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
f160: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
f170: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
f180: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
f190: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
f1a0: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
f1b0: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
f1c0: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
f1d0: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
f1e0: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
f1f0: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
f200: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
f210: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
f220: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
f230: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
f240: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
f250: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
f260: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
f270: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
f280: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
f290: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
f2a0: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
f2b0: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
f2c0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
f2d0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
f2e0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f2f0: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
f300: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
f310: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
f320: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
f330: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
f340: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
f350: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f360: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
f370: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f380: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
f390: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
f3a0: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
f3b0: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
f3c0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
f3d0: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
f3e0: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
f3f0: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
f400: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
f410: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
f420: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
f430: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
f440: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
f450: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
f460: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
f470: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
f480: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
f490: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
f4a0: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
f4b0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
f4c0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f4d0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
f4e0: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
f4f0: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
f500: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
f510: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
f520: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
f530: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
f540: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
f550: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
f560: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
f570: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
f580: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
f590: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
f5a0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
f5b0: 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49  lize(void);.SQLI
f5c0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
f5d0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
f5e0: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
f5f0: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
f600: 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  t(void);.SQLITE_
f610: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
f620: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
f630: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
f640: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
f650: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
f660: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
f670: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
f680: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
f690: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
f6a0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
f6b0: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
f6c0: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
f6d0: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
f6e0: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
f6f0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
f700: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
f710: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
f720: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
f730: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
f740: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
f750: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
f760: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
f770: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
f780: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
f790: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
f7a0: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
f7b0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
f7c0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
f7d0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
f7e0: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
f7f0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
f800: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
f810: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
f820: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
f830: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
f840: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
f850: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
f860: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
f870: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
f880: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f890: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
f8a0: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
f8b0: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
f8c0: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
f8d0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
f8e0: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
f8f0: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
f900: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f910: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
f920: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
f930: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
f940: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f950: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
f960: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
f970: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
f980: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
f990: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
f9a0: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
f9b0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f9c0: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
f9d0: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
f9e0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f9f0: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
fa00: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
fa10: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
fa20: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
fa30: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
fa40: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
fa50: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
fa60: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
fa70: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
fa80: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
fa90: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
faa0: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
fab0: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
fac0: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
fad0: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
fae0: 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
faf0: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
fb00: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
fb10: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
fb20: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
fb30: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
fb40: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
fb50: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
fb60: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
fb70: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
fb80: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
fb90: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
fba0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
fbb0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
fbc0: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
fbd0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
fbe0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
fbf0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
fc00: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
fc10: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
fc20: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
fc30: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
fc40: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
fc50: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
fc60: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
fc70: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
fc80: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
fc90: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
fca0: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
fcb0: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
fcc0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
fcd0: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
fce0: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
fcf0: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
fd00: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
fd10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
fd20: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
fd30: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
fd40: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
fd50: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
fd60: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
fd70: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
fd80: 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
fd90: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
fda0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
fdb0: 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
fdc0: 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
fdd0: 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
fde0: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
fdf0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
fe00: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
fe10: 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
fe20: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
fe30: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
fe40: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
fe50: 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
fe60: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
fe70: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
fe80: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
fe90: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
fea0: 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
feb0: 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
fec0: 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
fed0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f   int sqlite3_db_
fee0: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
fef0: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
ff00: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ff10: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
ff20: 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
ff30: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
ff40: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
ff50: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
ff60: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
ff70: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
ff80: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
ff90: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
ffa0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
ffb0: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
ffc0: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
ffd0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
ffe0: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
fff0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
10000 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
10010 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
10020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
10030 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
10040 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10050 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
10060 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
10070 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
10080 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
10090 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
100a0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
100b0 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
100c0 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
100d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
100e0 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
100f0 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
10100 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
10110 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
10120 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
10130 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
10140 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10150 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
10160 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
10170 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
10180 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
10190 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
101a0 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
101b0 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
101c0 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
101d0 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
101e0 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
101f0 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
10200 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
10210 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
10220 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
10230 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
10240 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
10250 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
10260 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
10270 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
10280 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
10290 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
102a0 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
102b0 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
102c0 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
102d0 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
102e0 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
102f0 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
10300 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
10310 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
10320 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
10330 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
10340 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
10350 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
10360 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
10370 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
10380 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
10390 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
103a0 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
103b0 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
103c0 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
103d0 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
103e0 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
103f0 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
10400 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
10410 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
10420 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
10430 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
10440 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
10450 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
10460 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
10470 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
10480 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
10490 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
104a0 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
104b0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
104c0 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
104d0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
104e0 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
104f0 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
10500 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
10510 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
10520 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
10530 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
10540 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
10550 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
10560 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
10570 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
10580 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
10590 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
105a0 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
105b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
105c0 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
105d0 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
105e0 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
105f0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
10600 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
10610 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
10620 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
10630 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
10640 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
10650 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
10660 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
10670 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
10680 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
10690 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
106a0 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
106b0 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
106c0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
106d0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
106e0 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
106f0 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
10700 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
10710 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
10720 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
10730 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
10740 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
10750 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
10760 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
10770 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
10780 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65  llocator.  For e
10790 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69  xample,.** it mi
107a0 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79  ght allocate any
107b0 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73   require mutexes
107c0 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69   or initialize i
107d0 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20  nternal data.** 
107e0 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65  structures.  The
107f0 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
10800 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e  d is invoked (in
10810 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20  directly) by.** 
10820 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
10830 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20  n()] and should 
10840 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  deallocate any r
10850 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65  esources acquire
10860 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20  d.** by xInit.  
10870 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69  The pAppData poi
10880 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20  nter is used as 
10890 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
108a0 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61  er to.** xInit a
108b0 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a  nd xShutdown..**
108c0 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73  .** SQLite holds
108d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
108e0 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
108f0 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20  ] mutex when it 
10900 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78  invokes.** the x
10910 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20  Init method, so 
10920 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
10930 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72   need not be thr
10940 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a  eadsafe.  The.**
10950 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
10960 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64  d is only called
10970 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
10980 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74  hutdown()] so it
10990 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65   does.** not nee
109a0 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61  d to be threadsa
109b0 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20  fe either.  For 
109c0 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64  all other method
109d0 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c  s, SQLite.** hol
109e0 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
109f0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d  UTEX_STATIC_MEM]
10a00 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61   mutex as long a
10a10 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
10a20 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
10a30 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  S] configuration
10a40 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65   option is turne
10a50 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69  d on (which.** i
10a60 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29  t is by default)
10a70 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68   and so the meth
10a80 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69  ods are automati
10a90 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64  cally serialized
10aa0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66  ..** However, if
10ab0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
10ac0 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69  MEMSTATUS] is di
10ad0 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  sabled, then the
10ae0 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64   other.** method
10af0 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  s must be thread
10b00 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b  safe or else mak
10b10 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61  e their own arra
10b20 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20  ngements for.** 
10b30 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  serialization..*
10b40 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  *.** SQLite will
10b50 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49   never invoke xI
10b60 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20  nit() more than 
10b70 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20  once without an 
10b80 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63  intervening.** c
10b90 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e  all to xShutdown
10ba0 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
10bb0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
10bc0 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
10bd0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
10be0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
10bf0 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
10c00 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
10c10 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
10c20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
10c30 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
10c40 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
10c50 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
10c60 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
10c70 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
10c80 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
10c90 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
10ca0 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
10cb0 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
10cc0 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
10cd0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
10ce0 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
10cf0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
10d00 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
10d10 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
10d20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
10d30 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
10d40 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
10d50 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
10d60 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
10d70 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
10d80 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
10d90 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
10da0 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
10db0 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
10dc0 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
10dd0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
10de0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
10df0 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
10e00 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
10e10 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
10e20 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
10e30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10e40 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
10e50 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
10e60 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f  S: {configuratio
10e70 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20  n option}.**.** 
10e80 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
10e90 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
10ea0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
10eb0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
10ec0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
10ed0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
10ee0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
10ef0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
10f00 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
10f10 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
10f20 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
10f30 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
10f40 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
10f50 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
10f60 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
10f70 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
10f80 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
10f90 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
10fa0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
10fb0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
10fc0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
10fd0 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
10fe0 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
10ff0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
11000 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
11010 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
11020 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
11030 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
11040 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
11050 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
11060 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
11070 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
11080 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
11090 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
110a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
110b0 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  GLETHREAD]] <dt>
110c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
110d0 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a  NGLETHREAD</dt>.
110e0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
110f0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
11100 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
11110 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
11120 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
11130 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67  ng mode] to Sing
11140 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  le-thread.  In o
11150 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
11160 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  isables.** all m
11170 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73  utexing and puts
11180 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d   SQLite into a m
11190 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e  ode where it can
111a0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a   only be used.**
111b0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
111c0 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ead.   ^If SQLit
111d0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
111e0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
111f0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
11200 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11210 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
11220 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
11230 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
11240 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  le to change the
11250 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11260 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75  ] from its defau
11270 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53  lt.** value of S
11280 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64  ingle-thread and
11290 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   so [sqlite3_con
112a0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
112b0 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rn .** [SQLITE_E
112c0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
112d0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
112e0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
112f0 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  EAD.** configura
11300 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
11310 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11320 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
11330 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
11340 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
11350 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
11360 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
11370 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
11380 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
11390 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
113a0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
113b0 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
113c0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
113d0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
113e0 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
113f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11400 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
11410 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
11420 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
11430 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
11440 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
11450 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
11460 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
11470 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
11480 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11490 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
114a0 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
114b0 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
114c0 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
114d0 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
114e0 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
114f0 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
11500 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
11510 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
11520 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
11530 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
11540 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
11550 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
11560 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
11570 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
11580 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
11590 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
115a0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
115b0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
115c0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
115d0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
115e0 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
115f0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
11600 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
11610 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
11620 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
11630 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
11640 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
11650 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
11660 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
11670 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
11680 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11690 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
116a0 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ZED]] <dt>SQLITE
116b0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
116c0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
116d0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
116e0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
116f0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
11700 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
11710 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11720 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20   to Serialized. 
11730 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11740 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62  this option enab
11750 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
11760 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65  es including the
11770 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75   recursive.** mu
11780 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61  texes on [databa
11790 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
117a0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
117b0 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
117c0 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65  .** In this mode
117d0 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64   (which is the d
117e0 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69  efault when SQLi
117f0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11800 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  ith.** [SQLITE_T
11810 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68  HREADSAFE=1]) th
11820 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
11830 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72   will itself ser
11840 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a  ialize access.**
11850 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
11860 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
11870 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11880 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65  nts] so that the
11890 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
118a0 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74  is free to use t
118b0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
118c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72  e connection] or
118d0 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72   the.** same [pr
118e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
118f0 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74  ] in different t
11900 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
11910 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20  me time..** ^If 
11920 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11930 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11940 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11950 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
11960 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
11970 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
11980 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
11990 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
119a0 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74  he Serialized [t
119b0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
119c0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
119d0 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
119e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
119f0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
11a00 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
11a10 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
11a20 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ED configuration
11a30 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
11a40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11a50 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  FIG_MALLOC]] <dt
11a60 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
11a70 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
11a80 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
11a90 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
11aa0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
11ab0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
11ac0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
11ad0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
11ae0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
11af0 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
11b00 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
11b10 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
11b20 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
11b30 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
11b40 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
11b50 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
11b60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11b70 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
11b80 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
11b90 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
11ba0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
11bb0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
11bc0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
11bd0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11be0 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
11bf0 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
11c00 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
11c10 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
11c20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11c30 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
11c40 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11c50 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
11c60 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
11c70 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
11c80 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
11c90 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
11ca0 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
11cb0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
11cc0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11cd0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
11ce0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
11cf0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
11d00 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
11d10 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
11d20 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
11d30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
11d40 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
11d50 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
11d60 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
11d70 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
11d80 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
11d90 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
11da0 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
11db0 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
11dc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
11dd0 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
11de0 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
11df0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64  or example. </dd
11e00 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11e10 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
11e20 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  S]] <dt>SQLITE_C
11e30 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
11e40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
11e50 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
11e60 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
11e70 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74  of type int, int
11e80 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a  erpreted as a .*
11e90 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68  * boolean, which
11ea0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
11eb0 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74  bles the collect
11ec0 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ion of memory al
11ed0 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61  location .** sta
11ee0 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20  tistics. ^(When 
11ef0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11f00 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
11f10 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a   disabled, the .
11f20 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  ** following SQL
11f30 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
11f40 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
11f50 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
11f60 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
11f70 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
11f80 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
11f90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
11fa0 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
11fb0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
11fc0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
11fd0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
11fe0 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a  ite3_status()].*
11ff0 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  *   </ul>)^.** ^
12000 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
12010 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
12020 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
12030 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74  ult unless SQLit
12040 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
12050 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
12060 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d  FAULT_MEMSTATUS]
12070 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  =0 in which case
12080 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
12090 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
120a0 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
120b0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64   default..** </d
120c0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
120d0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
120e0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
120f0 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74  NFIG_SCRATCH</dt
12100 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
12110 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
12120 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
12130 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
12140 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
12150 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
12160 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68  y.  There are th
12170 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20  ree arguments:  
12180 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62  A pointer an 8-b
12190 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d  yte.** aligned m
121a0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f  emory buffer fro
121b0 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61  m which the scra
121c0 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
121d0 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
121e0 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
121f0 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
12200 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
12210 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
12220 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
12230 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
12240 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
12250 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
12260 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a  multiple of 16..
12270 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
12280 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
12290 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
122a0 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
122b0 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
122c0 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
122d0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
122e0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20  ite will use no 
122f0 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63  more than two sc
12300 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65  ratch buffers pe
12310 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a  r thread.  So.**
12320 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74   N should be set
12330 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78   to twice the ex
12340 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e  pected maximum n
12350 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73  umber of threads
12360 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
12370 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20  l never require 
12380 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  a scratch buffer
12390 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68   that is more th
123a0 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68  an 6.** times th
123b0 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
123c0 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65  size. ^If SQLite
123d0 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64   needs needs add
123e0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74  itional.** scrat
123f0 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  ch memory beyond
12400 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
12410 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67  d by this config
12420 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20  uration option, 
12430 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  then .** [sqlite
12440 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c  3_malloc()] will
12450 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
12460 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65  in the memory ne
12470 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  eded.</dd>.**.**
12480 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12490 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74  _PAGECACHE]] <dt
124a0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
124b0 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
124c0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
124d0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
124e0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
124f0 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
12500 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74  can use for.** t
12510 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
12520 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
12530 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63  default page cac
12540 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
12550 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
12560 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
12570 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
12580 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
12590 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
125a0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
125b0 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
125c0 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ing the SQLITE_C
125d0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70  ONFIG_PCACHE2 op
125e0 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61  tion..** There a
125f0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
12600 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
12610 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  n: A pointer to 
12620 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a  8-byte aligned.*
12630 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
12640 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
12650 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
12660 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
12670 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
12680 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
12690 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
126a0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
126b0 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
126c0 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
126d0 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
126e0 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69  32768) plus a li
126f0 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65  ttle extra for e
12700 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64  ach.** page head
12710 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68  er.  ^The page h
12720 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30  eader size is 20
12730 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70   to 40 bytes dep
12740 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65  ending on.** the
12750 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75   host architectu
12760 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d  re.  ^It is harm
12770 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d  less, apart from
12780 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f   the wasted memo
12790 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73  ry,.** to make s
127a0 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c  z a little too l
127b0 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74  arge.  The first
127c0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
127d0 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  uld point to an 
127e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74  allocation of at
127f0 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
12800 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
12810 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
12820 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
12830 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ided by the firs
12840 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61  t argument to sa
12850 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d  tisfy its.** mem
12860 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68  ory needs for th
12870 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20  e first N pages 
12880 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20  that it adds to 
12890 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69  cache.  ^If addi
128a0 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
128b0 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
128c0 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
128d0 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
128e0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68   this option, th
128f0 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65  en.** SQLite goe
12900 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
12910 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20  lloc()] for the 
12920 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61  additional stora
12930 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65  ge space..** The
12940 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20   pointer in the 
12950 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
12960 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65  ust.** be aligne
12970 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
12980 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
12990 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
129a0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  f SQLite.** will
129b0 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   be undefined.</
129c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
129d0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d  TE_CONFIG_HEAP]]
129e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
129f0 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
12a00 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
12a10 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
12a20 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
12a30 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  er that SQLite w
12a40 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61  ill use.** for a
12a50 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
12a60 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
12a70 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64  ion needs beyond
12a80 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a   those provided.
12a90 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ** for by [SQLIT
12aa0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
12ab0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f  ] and [SQLITE_CO
12ac0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
12ad0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
12ae0 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41  ree arguments: A
12af0 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
12b00 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
12b10 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e  memory,.** the n
12b20 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
12b30 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66  n the memory buf
12b40 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e  fer, and the min
12b50 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
12b60 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  size..** ^If the
12b70 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
12b80 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
12b90 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  er) is NULL, the
12ba0 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73  n SQLite reverts
12bb0 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73  .** to using its
12bc0 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
12bd0 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73  allocator (the s
12be0 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69  ystem malloc() i
12bf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a  mplementation),.
12c00 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70  ** undoing any p
12c10 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20  rior invocation 
12c20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  of [SQLITE_CONFI
12c30 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20  G_MALLOC].  ^If 
12c40 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f  the.** memory po
12c50 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
12c60 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51  L and either [SQ
12c70 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
12c80 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  YS3] or.** [SQLI
12c90 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
12ca0 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20  5] are defined, 
12cb0 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61  then the alterna
12cc0 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tive memory.** a
12cd0 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61  llocator is enga
12ce0 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c  ged to handle al
12cf0 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d  l of SQLites mem
12d00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
12d10 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  eeds..** The fir
12d20 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
12d30 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
12d40 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
12d50 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
12d60 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
12d70 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
12d80 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  of SQLite will b
12d90 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
12da0 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  The minimum allo
12db0 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63  cation size is c
12dc0 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20  apped at 2**12. 
12dd0 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65  Reasonable value
12de0 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e  s.** for the min
12df0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
12e00 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68  size are 2**5 th
12e10 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e  rough 2**8.</dd>
12e20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12e30 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c  CONFIG_MUTEX]] <
12e40 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12e50 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
12e60 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
12e70 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
12e80 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
12e90 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
12ea0 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
12eb0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12ec0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
12ed0 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
12ee0 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
12ef0 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
12f00 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
12f10 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
12f20 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
12f30 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
12f40 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
12f50 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
12f60 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
12f70 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20   the.** content 
12f80 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12f90 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
12fa0 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
12fb0 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
12fc0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12fd0 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
12fe0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
12ff0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
13000 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13010 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
13020 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
13030 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
13040 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
13050 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
13060 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
13070 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
13080 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
13090 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
130a0 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
130b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
130c0 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
130d0 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
130e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
130f0 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
13100 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13110 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  _GETMUTEX]] <dt>
13120 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13130 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
13140 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
13150 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
13160 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
13170 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
13180 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
13190 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
131a0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
131b0 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
131c0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
131d0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
131e0 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
131f0 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
13200 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
13210 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
13220 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
13230 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
13240 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
13250 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
13260 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
13270 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
13280 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
13290 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
132a0 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
132b0 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
132c0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
132d0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
132e0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
132f0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
13300 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
13310 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
13320 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
13330 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
13340 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
13350 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
13360 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
13370 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
13380 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
13390 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
133a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
133b0 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
133c0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
133d0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
133e0 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
133f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13400 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13410 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13420 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
13430 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13440 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
13450 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
13460 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
13470 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f   default.** memo
13480 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
13490 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  r the lookaside 
134a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
134b0 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74   on each.** [dat
134c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
134d0 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
134e0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
134f0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
13500 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
13510 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
13520 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
13530 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
13540 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
13550 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13560 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70  on.)^  ^(This op
13570 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
13580 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
13590 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
135a0 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
135b0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
135c0 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69  ** verb to [sqli
135d0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
135e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
135f0 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
13600 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
13610 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
13620 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
13630 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
13640 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13650 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
13660 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13670 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
13680 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
13690 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
136a0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
136b0 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61   pointer to.** a
136c0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
136d0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
136e0 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
136f0 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69   specifies the i
13700 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61  nterface.** to a
13710 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
13720 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
13730 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  n.)^  ^SQLite ma
13740 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
13750 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20  e.** object and 
13760 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65  uses it for page
13770 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c   cache memory al
13780 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a  locations.</dd>.
13790 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
137a0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
137b0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
137c0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c  NFIG_GETPCACHE2<
137d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
137e0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
137f0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13800 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
13810 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
13820 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
13830 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
13840 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
13850 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
13860 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  * page cache imp
13870 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
13880 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
13890 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
138a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d  LITE_CONFIG_LOG]
138b0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
138c0 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
138d0 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
138e0 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
138f0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  n is used to con
13900 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74  figure the SQLit
13910 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72  e.** global [err
13920 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68  or log]..** (^Th
13930 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13940 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
13950 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
13960 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
13970 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
13980 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
13990 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
139a0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
139b0 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
139c0 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
139d0 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
139e0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
139f0 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
13a00 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
13a10 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
13a20 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
13a30 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
13a40 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
13a50 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
13a60 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
13a70 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
13a80 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
13a90 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
13aa0 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
13ab0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
13ac0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
13ad0 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
13ae0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
13af0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
13b00 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
13b10 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
13b20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
13b30 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
13b40 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
13b50 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
13b60 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
13b70 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
13b80 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
13b90 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
13ba0 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
13bb0 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
13bc0 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
13bd0 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
13be0 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
13bf0 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
13c00 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
13c10 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
13c20 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
13c30 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
13c40 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
13c50 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
13c60 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
13c70 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
13c80 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
13c90 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
13ca0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
13cb0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
13cc0 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
13cd0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
13ce0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
13cf0 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
13d00 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
13d10 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
13d20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
13d30 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
13d40 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
13d50 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
13d60 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
13d70 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13d80 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
13d90 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13da0 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69  URI.** <dd>^(Thi
13db0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
13dc0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13dd0 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66   of type int. If
13de0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a   non-zero, then.
13df0 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  ** URI handling 
13e00 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
13e10 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61  led. If the para
13e20 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74  meter is zero, t
13e30 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
13e40 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  .** is globally 
13e50 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20  disabled.)^ ^If 
13e60 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
13e70 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
13e80 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a  , all filenames.
13e90 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  ** passed to [sq
13ea0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
13eb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
13ec0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
13ed0 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65  n16()] or.** spe
13ee0 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f  cified as part o
13ef0 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61  f [ATTACH] comma
13f00 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  nds are interpre
13f10 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67  ted as URIs, reg
13f20 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68  ardless.** of wh
13f30 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
13f40 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
13f50 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  I] flag is set w
13f60 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
13f70 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
13f80 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74  s opened. ^If it
13f90 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
13fa0 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73  abled, filenames
13fb0 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74   are.** only int
13fc0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
13fd0 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f   if the SQLITE_O
13fe0 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20  PEN_URI flag is 
13ff0 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  set when the.** 
14000 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14010 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
14020 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49  (By default, URI
14030 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
14040 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65  bally.** disable
14050 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  d. The default v
14060 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e  alue may be chan
14070 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  ged by compiling
14080 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
14090 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79  LITE_USE_URI] sy
140a0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a  mbol defined.)^.
140b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
140c0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
140d0 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e  NDEX_SCAN]] <dt>
140e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
140f0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
14100 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f  N.** <dd>^This o
14110 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14120 6e 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67  ngle integer arg
14130 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69  ument which is i
14140 6e 74 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a  nterpreted as.**
14150 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72   a boolean in or
14160 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  der to enable or
14170 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65   disable the use
14180 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
14190 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c  ices for.** full
141a0 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20   table scans in 
141b0 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  the query optimi
141c0 7a 65 72 2e 20 20 5e 54 68 65 20 64 65 66 61 75  zer.  ^The defau
141d0 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65  lt setting is de
141e0 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74  termined.** by t
141f0 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57  he [SQLITE_ALLOW
14200 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
14210 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SCAN] compile-ti
14220 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73  me option, or is
14230 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74   "on".** if that
14240 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
14250 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e  tion is omitted.
14260 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20  .** The ability 
14270 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75  to disable the u
14280 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
14290 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20  ndices for full 
142a0 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69  table scans.** i
142b0 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69  s because some i
142c0 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64  ncorrectly coded
142d0 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74   legacy applicat
142e0 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75  ions might malfu
142f0 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74  nction.** when t
14300 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
14310 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f  is enabled.  Pro
14320 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69  viding the abili
14330 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65  ty to.** disable
14340 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
14350 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64  n allows the old
14360 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63  er, buggy applic
14370 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f  ation code to wo
14380 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68  rk.** without ch
14390 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e  ange even with n
143a0 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
143b0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b   SQLite..**.** [
143c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
143d0 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45  CACHE]] [[SQLITE
143e0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
143f0 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
14400 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
14410 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  and SQLITE_CONFI
14420 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c  G_GETPCACHE.** <
14430 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  dd> These option
14440 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61  s are obsolete a
14450 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  nd should not be
14460 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64   used by new cod
14470 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72  e..** They are r
14480 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b  etained for back
14490 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
144a0 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20  ity but are now 
144b0 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  no-ops..** </dd>
144c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
144d0 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a  CONFIG_SQLLOG]].
144e0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
144f0 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c  NFIG_SQLLOG.** <
14500 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  dd>This option i
14510 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
14520 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f   if sqlite is co
14530 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
14540 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
14550 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72  E_SQLLOG] pre-pr
14560 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65  ocessor macro de
14570 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74  fined. The first
14580 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
14590 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72  .** be a pointer
145a0 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
145b0 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76  f type void(*)(v
145c0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f  oid*,sqlite3*,co
145d0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e  nst char*, int).
145e0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73  .** The second s
145f0 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65  hould be of type
14600 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61   (void*). The ca
14610 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
14620 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79  d by the library
14630 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70  .** in three sep
14640 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e  arate circumstan
14650 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20  ces, identified 
14660 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73  by the value pas
14670 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f  sed as the.** fo
14680 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20  urth parameter. 
14690 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
146a0 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68  rameter is 0, th
146b0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
146c0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61  connection.** pa
146d0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
146e0 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  nd argument has 
146f0 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64  just been opened
14700 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  . The third argu
14710 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  ment.** points t
14720 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61  o a buffer conta
14730 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f  ining the name o
14740 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  f the main datab
14750 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65  ase file. If the
14760 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
14770 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20  eter is 1, then 
14780 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
14790 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64  t that the third
147a0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f   parameter.** po
147b0 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74  ints to has just
147c0 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20   been executed. 
147d0 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74  Or, if the fourt
147e0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32  h parameter is 2
147f0 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f  , then.** the co
14800 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70  nnection being p
14810 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
14820 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
14830 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54   being closed. T
14840 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
14850 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20  meter is passed 
14860 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73  NULL In this cas
14870 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f  e.  An example o
14880 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20  f using this.** 
14890 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
148a0 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e  tion can be seen
148b0 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71   in the "test_sq
148c0 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66  llog.c" source f
148d0 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61  ile in.** the ca
148e0 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73  nonical SQLite s
148f0 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e  ource tree.</dd>
14900 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14910 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
14920 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
14930 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
14940 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45  E.** <dd>^SQLITE
14950 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
14960 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62  E takes two 64-b
14970 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69  it integer (sqli
14980 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65  te3_int64) value
14990 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68  s.** that are th
149a0 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73  e default mmap s
149b0 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64  ize limit (the d
149c0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66  efault setting f
149d0 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d  or.** [PRAGMA mm
149e0 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68  ap_size]) and th
149f0 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
14a00 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  d mmap size limi
14a10 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  t..** ^The defau
14a20 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62  lt setting can b
14a30 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
14a40 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
14a50 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  nnection using.*
14a60 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52  * either the [PR
14a70 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20  AGMA mmap_size] 
14a80 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75  command, or by u
14a90 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  sing the.** [SQL
14aa0 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
14ab0 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
14ac0 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75  l.  ^(The maximu
14ad0 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
14ae0 69 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65  ize.** cannot be
14af0 20 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d   changed at run-
14b00 74 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74  time.  Nor may t
14b10 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
14b20 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
14b30 65 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69  exceed the compi
14b40 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
14b50 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
14b60 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
14b70 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
14b80 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14b90 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74  on.)^.** ^If eit
14ba0 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
14bb0 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e  this option is n
14bc0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
14bd0 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  at argument is.*
14be0 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73  * changed to its
14bf0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
14c00 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  fault..** </dl>.
14c10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14c20 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
14c30 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
14c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14c50 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
14c60 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
14c70 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
14c80 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
14c90 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
14ca0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
14cb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
14cc0 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
14cd0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14ce0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
14cf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14d00 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
14d10 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
14d20 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
14d30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14d40 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
14d50 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
14d60 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
14d70 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14d80 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
14d90 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
14da0 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
14db0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14dc0 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
14dd0 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
14de0 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
14df0 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
14e00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
14e10 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
14e20 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
14e30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14e40 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
14e50 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
14e60 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
14e70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14e80 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
14e90 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
14ea0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
14eb0 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
14ec0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
14ed0 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
14ee0 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
14ef0 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
14f00 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
14f10 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
14f20 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
14f30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14f40 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
14f50 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
14f60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14f70 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
14f80 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  15  /* no-op */.
14f90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14fa0 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
14fb0 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
14fc0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
14fd0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14fe0 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
14ff0 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
15000 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15010 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38  _PCACHE2      18
15020 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
15030 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
15040 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15050 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15060 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74  2   19  /* sqlit
15070 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
15080 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
15090 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
150a0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
150b0 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   20  /* int */.#
150c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
150d0 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20  NFIG_SQLLOG     
150e0 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67    21  /* xSqllog
150f0 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
15100 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15110 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32  _MMAP_SIZE    22
15120 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74    /* sqlite3_int
15130 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  64, sqlite3_int6
15140 34 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4 */../*.** CAPI
15150 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
15160 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
15170 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
15180 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
15190 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
151a0 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
151b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
151c0 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
151d0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
151e0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
151f0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
15200 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
15210 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
15220 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
15230 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
15240 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
15250 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
15260 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
15270 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
15280 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
15290 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
152a0 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
152b0 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
152c0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
152d0 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
152e0 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
152f0 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
15300 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
15310 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
15320 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
15330 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
15340 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
15350 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
15360 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
15370 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
15380 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15390 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
153a0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
153b0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
153c0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
153d0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
153e0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
153f0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
15400 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
15410 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
15420 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
15430 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
15440 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
15450 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
15460 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
15470 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
15480 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
15490 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
154a0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
154b0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
154c0 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
154d0 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
154e0 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
154f0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
15500 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
15510 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
15520 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
15530 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
15540 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
15550 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
15560 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
15570 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
15580 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
15590 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
155a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
155b0 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
155c0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
155d0 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
155e0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
155f0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
15600 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
15610 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
15620 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
15630 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
15640 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
15650 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
15660 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
15670 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
15680 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
15690 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
156a0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
156b0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
156c0 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
156d0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
156e0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
156f0 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
15700 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
15710 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
15720 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
15730 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
15740 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
15750 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
15760 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
15770 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
15780 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
15790 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
157a0 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
157b0 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
157c0 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
157d0 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
157e0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
157f0 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
15800 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
15810 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
15820 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
15830 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
15840 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
15850 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
15860 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
15870 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
15880 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
15890 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
158a0 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
158b0 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
158c0 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
158d0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
158e0 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
158f0 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
15900 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
15910 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
15920 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
15930 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
15940 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
15950 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
15960 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
15970 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
15980 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
15990 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
159a0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
159b0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
159c0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
159d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
159e0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
159f0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
15a00 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
15a10 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
15a20 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
15a30 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
15a40 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
15a50 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
15a60 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
15a70 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
15a80 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
15a90 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
15aa0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
15ab0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
15ac0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
15ad0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
15ae0 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
15af0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
15b00 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
15b10 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
15b20 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
15b30 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
15b40 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
15b50 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
15b60 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
15b70 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
15b80 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
15b90 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
15ba0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
15bb0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
15bc0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
15bd0 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
15be0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
15bf0 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
15c00 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
15c10 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
15c20 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
15c30 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
15c40 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
15c50 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
15c60 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
15c70 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
15c80 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
15c90 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
15ca0 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
15cb0 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
15cc0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
15cd0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
15ce0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
15cf0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
15d00 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
15d10 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
15d20 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
15d30 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
15d40 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
15d50 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
15d60 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
15d70 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
15d80 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
15d90 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
15da0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
15db0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
15dc0 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
15dd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
15de0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
15df0 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a  E       1001  /*
15e00 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
15e10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15e20 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
15e30 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20  _FKEY     1002  
15e40 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
15e50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
15e60 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
15e70 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20  IGGER  1003  /* 
15e80 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
15e90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
15ea0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
15eb0 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
15ec0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Codes.**.** ^The
15ed0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
15ee0 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
15ef0 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
15f00 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
15f10 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
15f20 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
15f30 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
15f40 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
15f50 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
15f60 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
15f70 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
15f80 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
15f90 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  y..*/.SQLITE_API
15fa0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74   int sqlite3_ext
15fb0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
15fc0 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
15fd0 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
15fe0 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
15ff0 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a  nsert Rowid.**.*
16000 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e  * ^Each entry in
16010 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62   most SQLite tab
16020 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20  les (except for 
16030 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
16040 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61  tables).** has a
16050 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
16060 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
16070 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
16080 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
16090 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73  ]. ^The rowid is
160a0 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
160b0 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
160c0 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
160d0 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
160e0 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
160f0 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
16100 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
16110 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
16120 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
16130 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65  umns. ^If.** the
16140 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
16150 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54  umn of type [INT
16160 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
16170 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  ] then that colu
16180 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
16190 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
161a0 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  owid..**.** ^The
161b0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
161c0 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e  sert_rowid(D) in
161d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
161e0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
161f0 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  he .** most rece
16200 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  nt successful [I
16210 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f  NSERT] into a ro
16220 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69  wid table or [vi
16230 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
16240 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  on database conn
16250 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e  ection D..** ^In
16260 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48  serts into [WITH
16270 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
16280 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64  s are not record
16290 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75  ed..** ^If no su
162a0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
162b0 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61  ]s into rowid ta
162c0 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  bles.** have eve
162d0 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
162e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
162f0 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65  ction D, .** the
16300 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  n sqlite3_last_i
16310 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72  nsert_rowid(D) r
16320 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
16330 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
16340 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
16350 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77  n a trigger or w
16360 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c  ithin a [virtual
16370 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f   table].** metho
16380 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  d, then this rou
16390 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  tine will return
163a0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
163b0 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
163c0 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  row as long as t
163d0 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
163e0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
163f0 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  od is running..*
16400 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74  * But once the t
16410 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
16420 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65  l table method e
16430 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
16440 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
16450 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
16460 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
16470 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
16480 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
16490 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  .** table method
164a0 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20   began.)^.**.** 
164b0 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
164c0 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
164d0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
164e0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
164f0 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
16500 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
16510 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
16520 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
16530 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
16540 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
16550 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
16560 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
16570 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
16580 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
16590 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
165a0 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
165b0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
165c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
165d0 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
165e0 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
165f0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
16600 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
16610 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
16620 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
16630 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
16640 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
16650 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
16660 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
16670 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
16680 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
16690 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
166a0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
166b0 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
166c0 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
166d0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
166e0 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
166f0 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
16700 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
16710 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
16720 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
16730 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
16740 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
16750 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
16760 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
16770 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
16780 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
16790 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
167a0 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
167b0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
167c0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
167d0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
167e0 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
167f0 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
16800 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
16810 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16820 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
16830 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
16840 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
16850 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
16860 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
16870 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
16880 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
16890 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
168a0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
168b0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
168c0 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
168d0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
168e0 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
168f0 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
16900 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
16910 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
16920 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
16930 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
16940 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
16950 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
16960 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
16970 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
16980 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
16990 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
169a0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
169b0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
169c0 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
169d0 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
169e0 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
169f0 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
16a00 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
16a10 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
16a20 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
16a30 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
16a40 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
16a50 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
16a60 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28  parameter..** ^(
16a70 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
16a80 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
16a90 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
16aa0 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
16ab0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
16ac0 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
16ad0 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
16ae0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
16af0 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
16b00 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b  rs or [foreign k
16b10 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
16b20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55  not counted.)^ U
16b30 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
16b40 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
16b50 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ()] function to 
16b60 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e  find the total n
16b70 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
16b80 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  .** including ch
16b90 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
16ba0 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72  triggers and for
16bb0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
16bc0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  ..**.** ^Changes
16bd0 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
16be0 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79  are simulated by
16bf0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
16c00 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20  trigger].** are 
16c10 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e  not counted.  On
16c20 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68  ly real table ch
16c30 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
16c40 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f  d..**.** ^(A "ro
16c50 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
16c60 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
16c70 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
16c80 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
16c90 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
16ca0 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
16cb0 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
16cc0 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
16cd0 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
16ce0 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41  ffects of [REPLA
16cf0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
16d00 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f  esolution,.** ro
16d10 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72  llback, ABORT pr
16d20 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20  ocessing, [DROP 
16d30 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e  TABLE], or by an
16d40 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
16d50 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
16d60 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
16d70 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a   changes.)^.**.*
16d80 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
16d90 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
16da0 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
16db0 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
16dc0 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
16dd0 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41  cript of a [CREA
16de0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
16df0 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20  gger]. .** Most 
16e00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
16e10 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
16e20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
16e30 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
16e40 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
16e50 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
16e60 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
16e70 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
16e80 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
16e90 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
16ea0 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
16eb0 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
16ec0 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
16ed0 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
16ee0 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
16ef0 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
16f00 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
16f10 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71  .** ^Calling [sq
16f20 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72  lite3_exec()] or
16f30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
16f40 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f  ] recursively do
16f50 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65  es.** not create
16f60 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63   a new trigger c
16f70 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
16f80 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
16f90 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
16fa0 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  of direct row ch
16fb0 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  anges in the.** 
16fc0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
16fd0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
16fe0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
16ff0 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a  within the same.
17000 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
17010 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c  xt..**.** ^Thus,
17020 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
17030 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
17040 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
17050 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
17060 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
17070 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
17080 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
17090 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
170a0 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72  that also occurr
170b0 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65  ed at the top le
170c0 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74  vel.  ^(Within t
170d0 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
170e0 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
170f0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
17100 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
17110 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
17120 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
17130 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
17140 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
17150 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
17160 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
17170 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
17180 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
17190 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
171a0 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
171b0 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
171c0 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
171d0 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
171e0 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
171f0 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
17200 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
17210 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a  context.)^.**.**
17220 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also 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 69 6e 74 65 72 66 61 63  nges()] interfac
17250 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
17260 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
17270 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
17280 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
17290 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
172a0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
172b0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
172c0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
172d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
172e0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
172f0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
17300 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
17310 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
17320 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
17330 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
17340 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
17350 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
17360 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
17370 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17380 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
17390 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
173a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
173b0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
173c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
173d0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
173e0 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b  y [INSERT],.** [
173f0 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
17400 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73  TE] statements s
17410 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
17420 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
17430 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28  as opened..** ^(
17440 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e  The count return
17450 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
17460 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  tal_changes() in
17470 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
17480 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b  es.** from all [
17490 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
174a0 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
174b0 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d  ts and changes m
174c0 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69  ade by.** [forei
174d0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e  gn key actions].
174e0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
174f0 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
17500 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
17510 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
17520 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  t [REPLACE] cons
17530 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72  traints,.** do r
17540 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52  ollbacks or ABOR
17550 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72  T processing, or
17560 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72   [DROP TABLE] pr
17570 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a  ocessing.  The.*
17580 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  * count does not
17590 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66   include rows of
175a0 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65   views that fire
175b0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
175c0 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f  trigger],.** tho
175d0 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45  ugh if the INSTE
175e0 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61  AD OF trigger ma
175f0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69  kes changes of i
17600 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68  ts own, those ch
17610 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f  anges .** are co
17620 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65  unted.)^.** ^The
17630 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
17640 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
17650 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61  n counts the cha
17660 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a  nges as soon as.
17670 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
17680 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
17690 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
176a0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
176b0 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70  t handle.** is p
176c0 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
176d0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
176e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
176f0 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
17700 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
17710 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
17720 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
17730 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
17740 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
17750 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
17760 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
17770 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
17780 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
17790 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
177a0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
177b0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
177c0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
177d0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
177e0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
177f0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
17800 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
17810 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
17820 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
17830 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  PI int sqlite3_t
17840 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
17850 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
17860 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
17870 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
17880 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
17890 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
178a0 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
178b0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
178c0 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
178d0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
178e0 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
178f0 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
17900 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
17910 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
17920 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
17930 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
17940 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
17950 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
17960 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
17970 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
17980 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
17990 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
179a0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
179b0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
179c0 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
179d0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
179e0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
179f0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
17a00 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
17a10 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
17a20 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
17a30 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
17a40 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
17a50 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
17a60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
17a70 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
17a80 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
17a90 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
17aa0 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
17ab0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
17ac0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
17ad0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
17ae0 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
17af0 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
17b00 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
17b10 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
17b20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
17b30 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
17b40 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
17b50 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
17b60 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
17b70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
17b80 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
17b90 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
17ba0 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
17bb0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
17bc0 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
17bd0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
17be0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
17bf0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
17c00 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
17c10 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
17c20 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
17c30 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
17c40 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
17c50 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
17c60 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
17c70 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
17c80 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
17c90 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
17ca0 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
17cb0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
17cc0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
17cd0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
17ce0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
17cf0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
17d00 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
17d10 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
17d20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
17d30 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
17d40 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
17d50 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
17d60 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
17d70 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
17d80 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
17d90 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
17da0 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
17db0 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
17dc0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
17dd0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
17de0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
17df0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
17e00 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
17e10 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
17e20 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
17e30 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
17e40 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
17e50 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
17e60 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
17e70 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
17e80 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
17e90 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
17ea0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
17eb0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
17ec0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
17ed0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
17ee0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
17ef0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
17f00 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
17f10 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
17f20 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
17f30 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
17f40 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
17f50 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
17f60 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
17f70 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
17f80 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
17f90 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53  ely happen..*/.S
17fa0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
17fb0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
17fc0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
17fd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
17fe0 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
17ff0 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
18000 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
18010 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
18020 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
18030 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
18040 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
18050 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
18060 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
18070 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
18080 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
18090 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
180a0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
180b0 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
180c0 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
180d0 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
180e0 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
180f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
18100 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
18110 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
18120 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
18130 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
18140 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
18150 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
18160 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
18170 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
18180 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
18190 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
181a0 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
181b0 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
181c0 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
181d0 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
181e0 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
181f0 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
18200 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
18210 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
18220 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
18230 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
18240 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
18250 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
18260 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
18270 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
18280 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
18290 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
182a0 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
182b0 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
182c0 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
182d0 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
182e0 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
182f0 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
18300 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
18310 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
18320 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
18330 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
18340 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
18350 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
18360 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
18370 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
18380 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
18390 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
183a0 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
183b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
183c0 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
183d0 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
183e0 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
183f0 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
18400 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
18410 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
18420 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
18430 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
18440 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
18450 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
18460 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
18470 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
18480 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
18490 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
184a0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
184b0 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
184c0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
184d0 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
184e0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
184f0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
18500 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
18510 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
18520 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
18530 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
18540 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
18550 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
18560 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
18570 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
18580 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
18590 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
185a0 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
185b0 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
185c0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
185d0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
185e0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
185f0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
18600 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
18610 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  der..*/.SQLITE_A
18620 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
18630 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
18640 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45  ar *sql);.SQLITE
18650 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
18660 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
18670 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
18680 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
18690 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
186a0 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
186b0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
186c0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
186d0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
186e0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
186f0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
18700 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
18710 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
18720 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
18730 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
18740 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
18750 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
18760 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
18770 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
18780 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
18790 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
187a0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
187b0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
187c0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
187d0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
187e0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
187f0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
18800 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
18810 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
18820 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
18830 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
18840 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
18850 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
18860 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
18870 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
18880 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
18890 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
188a0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
188b0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
188c0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
188d0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
188e0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
188f0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
18900 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
18910 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
18920 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
18930 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
18940 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
18950 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
18960 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
18970 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
18980 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
18990 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
189a0 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
189b0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
189c0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
189d0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
189e0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
189f0 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
18a00 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
18a10 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
18a20 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
18a30 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
18a40 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
18a50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
18a60 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
18a70 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
18a80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
18a90 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
18aa0 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
18ab0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
18ac0 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
18ad0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
18ae0 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
18af0 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
18b00 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
18b10 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
18b20 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
18b30 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
18b40 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
18b50 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
18b60 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
18b70 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
18b80 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
18b90 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
18ba0 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
18bb0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
18bc0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
18bd0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
18be0 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
18bf0 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
18c00 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
18c10 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
18c20 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
18c30 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
18c40 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
18c50 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
18c60 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
18c70 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
18c80 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
18c90 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
18ca0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
18cb0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
18cc0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
18cd0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
18ce0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
18cf0 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
18d00 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
18d10 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
18d20 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
18d30 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
18d40 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
18d50 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
18d60 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
18d70 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
18d80 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
18d90 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
18da0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
18db0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
18dc0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
18dd0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
18de0 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
18df0 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
18e00 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
18e10 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
18e20 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
18e30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
18e40 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
18e50 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
18e60 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
18e70 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
18e80 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
18e90 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
18ea0 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
18eb0 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
18ec0 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
18ed0 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
18ee0 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
18ef0 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
18f00 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
18f10 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
18f20 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
18f30 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
18f40 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
18f50 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
18f60 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
18f70 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
18f80 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
18f90 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
18fa0 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
18fb0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
18fc0 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
18fd0 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
18fe0 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
18ff0 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
19000 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
19010 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
19020 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
19030 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
19040 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
19050 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
19060 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
19070 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
19080 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
19090 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
190a0 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
190b0 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
190c0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
190d0 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
190e0 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
190f0 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
19100 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
19110 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
19120 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
19130 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
19140 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
19150 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
19160 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
19170 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
19180 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
19190 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
191a0 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
191b0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
191c0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
191d0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
191e0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
191f0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
19200 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
19210 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
19220 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
19230 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
19240 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
19250 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
19260 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
19270 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
19280 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
19290 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
192a0 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
192b0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
192c0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
192d0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
192e0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
192f0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
19300 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19310 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
19320 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19330 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
19340 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
19350 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
19360 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
19370 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
19380 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
19390 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
193a0 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
193b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
193c0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
193d0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53  sy handler..*/.S
193e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
193f0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
19400 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
19410 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
19420 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
19430 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
19440 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a  usy Timeout.**.*
19450 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
19460 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
19470 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
19480 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
19490 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
194a0 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
194b0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
194c0 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
194d0 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
194e0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
194f0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
19500 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
19510 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
19520 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
19530 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
19540 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
19550 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
19560 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
19570 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
19580 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
19590 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
195a0 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
195b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
195c0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
195d0 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a  RR_BLOCKED]..**.
195e0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
195f0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
19600 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
19610 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
19620 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
19630 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
19640 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
19650 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
19660 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
19670 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
19680 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
19690 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
196a0 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  ny any given mom
196b0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
196c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
196d0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
196e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
196f0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
19700 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
19710 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
19720 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
19730 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
19740 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  red.)^.*/.SQLITE
19750 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
19760 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
19770 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
19780 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19790 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
197a0 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
197b0 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
197c0 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
197d0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
197e0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
197f0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
19800 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
19810 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
19820 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
19830 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
19840 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
19850 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
19860 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
19870 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
19880 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
19890 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
198a0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
198b0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
198c0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
198d0 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
198e0 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
198f0 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
19900 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
19910 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
19920 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
19930 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
19940 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
19950 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
19960 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
19970 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
19980 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
19990 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
199a0 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
199b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
199c0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
199d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
199e0 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
199f0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
19a00 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
19a10 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
19a20 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
19a30 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
19a40 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
19a50 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
19a60 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
19a70 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
19a80 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
19a90 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
19aa0 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
19ab0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
19ac0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
19ad0 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
19ae0 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
19af0 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
19b00 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
19b10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
19b20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
19b30 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
19b40 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
19b50 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
19b60 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
19b70 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
19b80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
19b90 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
19ba0 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
19bb0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
19bc0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
19bd0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
19be0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
19bf0 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
19c00 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
19c10 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
19c20 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
19c30 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
19c40 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
19c50 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
19c60 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
19c70 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
19c80 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
19c90 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
19ca0 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
19cb0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
19cc0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
19cd0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
19ce0 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
19cf0 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
19d00 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
19d10 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
19d20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
19d30 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
19d40 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
19d50 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
19d60 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
19d70 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
19d80 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
19d90 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
19da0 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
19db0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
19dc0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
19dd0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
19de0 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
19df0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
19e00 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
19e10 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
19e20 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
19e30 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
19e40 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
19e50 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
19e60 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
19e70 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
19e80 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
19e90 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
19ea0 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
19eb0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
19ec0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
19ed0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
19ee0 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
19ef0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
19f00 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
19f10 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
19f20 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
19f30 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
19f40 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
19f50 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
19f60 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
19f70 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
19f80 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
19f90 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
19fa0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
19fb0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
19fc0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
19fd0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
19fe0 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
19ff0 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1a000 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1a010 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1a020 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1a030 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1a040 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1a050 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1a060 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1a070 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1a080 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1a090 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1a0a0 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1a0b0 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1a0c0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1a0d0 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1a0e0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1a0f0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1a100 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1a110 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1a120 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1a130 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1a140 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1a150 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1a160 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1a170 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1a180 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1a190 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1a1a0 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1a1b0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1a1c0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1a1d0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1a1e0 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1a1f0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1a200 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1a210 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1a220 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1a230 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1a240 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a250 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1a260 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1a270 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1a280 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1a290 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1a2a0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1a2b0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1a2c0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1a2d0 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1a2e0 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1a2f0 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1a300 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1a310 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1a320 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1a330 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1a340 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1a350 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1a360 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1a370 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1a380 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1a390 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1a3a0 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1a3b0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1a3c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1a3d0 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1a3e0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1a3f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1a400 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
1a410 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1a420 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1a430 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1a440 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1a450 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1a460 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1a470 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1a480 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1a490 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1a4a0 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1a4b0 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1a4c0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1a4d0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1a4e0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1a4f0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1a500 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1a510 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1a520 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1a530 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1a540 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1a550 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1a560 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
1a570 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  I void sqlite3_f
1a580 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1a590 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1a5a0 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1a5b0 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1a5c0 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1a5d0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1a5e0 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1a5f0 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1a600 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1a610 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1a620 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1a630 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
1a640 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1a650 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1a660 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1a670 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1a680 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1a690 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1a6a0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1a6b0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1a6c0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1a6d0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1a6e0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1a6f0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1a700 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1a710 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1a720 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1a730 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1a740 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1a750 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1a760 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1a770 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1a780 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1a790 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1a7a0 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1a7b0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1a7c0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1a7d0 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1a7e0 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1a7f0 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1a800 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1a810 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1a820 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1a830 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1a840 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1a850 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1a860 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1a870 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1a880 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1a890 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1a8a0 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1a8b0 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1a8c0 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1a8d0 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1a8e0 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1a8f0 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1a900 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1a910 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1a920 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1a930 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1a940 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1a950 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1a960 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1a970 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1a980 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1a990 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1a9a0 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1a9b0 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1a9c0 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1a9d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1a9e0 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1a9f0 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1aa00 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1aa10 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1aa20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1aa30 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1aa40 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1aa50 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1aa60 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1aa70 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1aa80 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1aa90 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1aaa0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1aab0 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1aac0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1aad0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1aae0 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1aaf0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1ab00 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1ab10 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1ab20 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1ab30 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1ab40 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1ab50 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1ab60 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1ab70 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1ab80 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1ab90 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1aba0 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1abb0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1abc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1abd0 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1abe0 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1abf0 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1ac00 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1ac10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1ac20 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1ac30 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1ac40 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1ac50 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1ac60 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1ac70 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1ac80 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1ac90 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1aca0 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1acb0 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1acc0 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1acd0 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1ace0 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
1acf0 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
1ad00 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
1ad10 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
1ad20 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
1ad30 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65  titutes a nul-te
1ad40 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1ad50 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
1ad60 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
1ad70 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
1ad80 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
1ad90 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
1ada0 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
1adb0 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
1adc0 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
1add0 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
1ade0 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
1adf0 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
1ae00 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
1ae10 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
1ae20 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
1ae30 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
1ae40 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
1ae50 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
1ae60 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
1ae70 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
1ae80 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1ae90 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1aea0 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
1aeb0 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
1aec0 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
1aed0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1aee0 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
1aef0 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
1af00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
1af10 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1af20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1af30 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1af40 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1af50 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1af60 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
1af70 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
1af80 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1af90 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1afa0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1afb0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1afc0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1afd0 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1afe0 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
1aff0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
1b000 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
1b010 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
1b020 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
1b030 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
1b040 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1b050 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1b060 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1b070 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1b080 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
1b090 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
1b0a0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1b0b0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
1b0c0 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
1b0d0 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
1b0e0 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
1b0f0 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
1b100 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
1b110 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
1b120 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1b130 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1b140 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1b150 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1b160 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1b170 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1b180 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
1b190 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
1b1a0 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
1b1b0 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
1b1c0 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
1b1d0 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
1b1e0 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
1b1f0 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
1b200 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
1b210 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
1b220 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
1b230 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
1b240 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
1b250 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
1b260 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
1b270 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
1b280 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
1b290 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
1b2a0 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
1b2b0 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
1b2c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
1b2d0 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
1b2e0 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
1b2f0 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
1b300 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
1b310 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
1b320 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
1b330 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1b340 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1b350 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1b360 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1b370 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1b380 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
1b390 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1b3a0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1b3b0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1b3c0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1b3d0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1b3e0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
1b3f0 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
1b400 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
1b410 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
1b420 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
1b430 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
1b440 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
1b450 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1b460 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1b470 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1b480 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1b490 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1b4a0 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1b4b0 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1b4c0 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1b4d0 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1b4e0 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1b4f0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1b500 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1b510 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1b520 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
1b530 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d   char *sqlite3_m
1b540 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1b550 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f  r*,...);.SQLITE_
1b560 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
1b570 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
1b580 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1b590 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1b5a0 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
1b5b0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1b5c0 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
1b5d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1b5e0 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69   *sqlite3_vsnpri
1b5f0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1b600 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1b610 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  st);../*.** CAPI
1b620 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1b630 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
1b640 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
1b650 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
1b660 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
1b670 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
1b680 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
1b690 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1b6a0 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
1b6b0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
1b6c0 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
1b6d0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
1b6e0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
1b6f0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
1b700 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
1b710 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
1b720 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
1b730 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1b740 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
1b750 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
1b760 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b770 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1b780 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1b790 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
1b7a0 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
1b7b0 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
1b7c0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
1b7d0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
1b7e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b7f0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
1b800 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
1b810 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
1b820 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
1b830 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
1b840 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
1b850 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
1b860 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
1b870 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
1b880 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b890 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
1b8a0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1b8b0 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
1b8c0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
1b8d0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
1b8e0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
1b8f0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1b900 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1b910 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
1b920 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
1b930 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
1b940 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
1b950 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
1b960 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
1b970 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
1b980 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1b990 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
1b9a0 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
1b9b0 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
1b9c0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
1b9d0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
1b9e0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
1b9f0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
1ba00 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
1ba10 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
1ba20 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
1ba30 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
1ba40 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
1ba50 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1ba60 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
1ba70 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
1ba80 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
1ba90 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1baa0 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
1bab0 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
1bac0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
1bad0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1bae0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1baf0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
1bb00 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
1bb10 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1bb20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1bb30 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1bb40 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  oc()..**.** ^(Th
1bb50 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1bb60 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
1bb70 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
1bb80 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
1bb90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
1bba0 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
1bbb0 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
1bbc0 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
1bbd0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
1bbe0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1bbf0 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
1bc00 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
1bc10 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66  arameter.)^ ^ If
1bc20 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1bc30 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1bc40 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
1bc50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1bc60 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
1bc70 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
1bc80 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1bc90 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
1bca0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
1bcb0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1bcc0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1bcd0 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  ()..** ^If the s
1bce0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1bcf0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1bd00 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
1bd10 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1bd20 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1bd30 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1bd40 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1bd50 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
1bd60 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
1bd70 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1bd80 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1bd90 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  c()..** ^sqlite3
1bda0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
1bdb0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1bdc0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1bdd0 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
1bde0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
1bdf0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
1be00 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
1be10 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
1be20 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
1be30 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
1be40 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
1be50 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
1be60 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
1be70 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
1be80 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
1be90 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
1bea0 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
1beb0 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
1bec0 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
1bed0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1bee0 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
1bef0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1bf00 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
1bf10 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
1bf20 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
1bf30 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
1bf40 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1bf50 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1bf60 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
1bf70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
1bf80 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1bf90 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1bfa0 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1bfb0 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1bfc0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1bfd0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1bfe0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1bff0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1c000 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1c010 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1c020 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1c030 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1c040 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1c050 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1c060 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1c070 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1c080 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1c090 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1c0a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1c0b0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1c0c0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1c0d0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1c0e0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1c0f0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1c100 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1c110 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1c120 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1c130 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1c140 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1c150 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1c160 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1c170 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1c180 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1c190 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1c1a0 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1c1b0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1c1c0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1c1d0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1c1e0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1c1f0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1c200 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1c210 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1c220 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1c230 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1c240 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1c250 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1c260 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1c270 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1c280 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1c290 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1c2a0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1c2b0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1c2c0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1c2d0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1c2e0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1c2f0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1c300 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c310 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1c320 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1c330 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1c340 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1c350 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1c360 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1c370 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1c380 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1c390 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1c3a0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1c3b0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1c3c0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1c3d0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1c3e0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1c3f0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1c400 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1c410 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1c420 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1c430 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1c440 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  alloc()]..*/.SQL
1c450 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
1c460 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1c470 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1c480 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1c490 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1c4a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1c4b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
1c4c0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1c4d0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1c4e0 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
1c4f0 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  cs.**.** SQLite 
1c500 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
1c510 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
1c520 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
1c530 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
1c540 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
1c550 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
1c560 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
1c570 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c580 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
1c590 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
1c5a0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1c5b0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
1c5c0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  em..**.** ^The [
1c5d0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1c5e0 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
1c5f0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1c600 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66  r of bytes.** of
1c610 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
1c620 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
1c630 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
1c640 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20  freed)..** ^The 
1c650 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1c660 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
1c670 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1c680 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75   maximum.** valu
1c690 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
1c6a0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e  mory_used()] sin
1c6b0 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
1c6c0 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61  r mark.** was la
1c6d0 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20  st reset.  ^The 
1c6e0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
1c6f0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1c700 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a  ry_used()] and.*
1c710 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1c720 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1c730 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
1c740 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20  ead.** added by 
1c750 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d  SQLite in its im
1c760 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1c770 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1c780 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f  )],.** but not o
1c790 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79  verhead added by
1c7a0 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79   the any underly
1c7b0 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61  ing system libra
1c7c0 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  ry.** routines t
1c7d0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
1c7e0 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
1c7f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1c800 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  ry high-water ma
1c810 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
1c820 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
1c830 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
1c840 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
1c850 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
1c860 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
1c870 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1c880 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1c890 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61  s true.  ^The va
1c8a0 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
1c8b0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1c8c0 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d  ry_highwater(1)]
1c8d0 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74   is the high-wat
1c8e0 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72  er mark.** prior
1c8f0 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
1c900 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
1c910 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1c920 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
1c930 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
1c940 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
1c950 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1c960 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
1c970 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
1c980 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
1c990 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
1c9a0 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
1c9b0 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
1c9c0 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
1c9d0 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
1c9e0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
1c9f0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
1ca00 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
1ca10 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
1ca20 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
1ca30 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
1ca40 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
1ca50 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
1ca60 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
1ca70 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
1ca80 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
1ca90 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
1caa0 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
1cab0 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
1cac0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
1cad0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
1cae0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
1caf0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
1cb00 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
1cb10 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
1cb20 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
1cb30 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
1cb40 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
1cb50 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
1cb60 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e  uffer P..**.** ^
1cb70 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
1cb80 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
1cb90 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69  nvoked (either i
1cba0 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a  nternally or by.
1cbb0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
1cbc0 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20  on) the PRNG is 
1cbd0 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
1cbe0 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
1cbf0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61  .** from the xRa
1cc00 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1cc10 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
1cc20 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1cc30 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20  ect..** ^On all 
1cc40 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
1cc50 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75  ations, the pseu
1cc60 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
1cc70 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
1cc80 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
1cc90 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
1cca0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1ccb0 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
1ccc0 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c  * method..*/.SQL
1ccd0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
1cce0 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
1ccf0 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
1cd00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1cd10 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
1cd20 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
1cd30 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
1cd40 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
1cd50 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a  ters an authoriz
1cd60 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
1cd70 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1cd80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1cd90 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
1cda0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
1cdb0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
1cdc0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1cdd0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
1cde0 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
1cdf0 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
1ce00 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
1ce10 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1ce20 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
1ce30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1ce40 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
1ce50 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
1ce60 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
1ce70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
1ce80 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
1ce90 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
1cea0 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
1ceb0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
1cec0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
1ced0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
1cee0 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
1cef0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1cf00 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1cf10 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
1cf20 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
1cf30 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
1cf40 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1cf50 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
1cf60 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
1cf70 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
1cf80 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
1cf90 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
1cfa0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
1cfb0 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
1cfc0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1cfd0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
1cfe0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
1cff0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1d000 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
1d010 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
1d020 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
1d030 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
1d040 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
1d050 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d060 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
1d070 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
1d080 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
1d090 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
1d0a0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1d0b0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
1d0c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1d0d0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1d0e0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1d0f0 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
1d100 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1d110 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1d120 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
1d130 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1d140 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1d150 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
1d160 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
1d170 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
1d180 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
1d190 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1d1a0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
1d1b0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
1d1c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1d1d0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1d1e0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
1d1f0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1d200 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1d210 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1d220 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
1d230 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
1d240 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
1d250 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1d260 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
1d270 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1d280 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
1d290 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
1d2a0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1d2b0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1d2c0 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
1d2d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1d2e0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
1d2f0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1d300 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
1d310 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
1d320 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
1d330 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1d340 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
1d350 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
1d360 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
1d370 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
1d380 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1d390 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
1d3a0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
1d3b0 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
1d3c0 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
1d3d0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
1d3e0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1d3f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1d400 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
1d410 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
1d420 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1d430 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1d440 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1d450 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
1d460 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
1d470 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
1d480 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
1d490 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
1d4a0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
1d4b0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
1d4c0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
1d4d0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
1d4e0 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
1d4f0 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
1d500 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
1d510 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
1d520 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
1d530 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
1d540 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
1d550 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
1d560 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
1d570 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1d580 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1d590 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
1d5a0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1d5b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
1d5c0 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
1d5d0 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
1d5e0 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
1d5f0 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
1d600 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
1d610 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
1d620 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
1d630 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
1d640 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
1d650 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
1d660 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d670 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
1d680 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1d690 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
1d6a0 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
1d6b0 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
1d6c0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
1d6d0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
1d6e0 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
1d6f0 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
1d700 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
1d710 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
1d720 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
1d730 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
1d740 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
1d750 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
1d760 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
1d770 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
1d780 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
1d790 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
1d7a0 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
1d7b0 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
1d7c0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
1d7d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1d7e0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
1d7f0 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
1d800 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
1d810 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
1d820 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
1d830 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
1d840 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
1d850 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
1d860 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
1d870 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
1d880 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
1d890 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
1d8a0 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
1d8b0 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
1d8c0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
1d8d0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
1d8e0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
1d8f0 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
1d900 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
1d910 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
1d920 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
1d930 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
1d940 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
1d950 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
1d960 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
1d970 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
1d980 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
1d990 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
1d9a0 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
1d9b0 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
1d9c0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
1d9d0 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
1d9e0 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
1d9f0 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
1da00 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
1da10 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
1da20 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
1da30 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
1da40 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
1da50 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
1da60 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
1da70 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
1da80 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
1da90 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
1daa0 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
1dab0 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
1dac0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
1dad0 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
1dae0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
1daf0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
1db00 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
1db10 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
1db20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1db30 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1db40 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1db50 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
1db60 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
1db70 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
1db80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
1db90 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
1dba0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1dbb0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
1dbc0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
1dbd0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
1dbe0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
1dbf0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1dc00 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
1dc10 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
1dc20 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
1dc30 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
1dc40 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
1dc50 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
1dc60 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
1dc70 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
1dc80 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
1dc90 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
1dca0 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
1dcb0 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
1dcc0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1dcd0 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
1dce0 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
1dcf0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1dd00 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
1dd10 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1dd20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1dd30 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
1dd40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1dd50 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1dd60 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
1dd70 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
1dd80 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
1dd90 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
1dda0 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
1ddb0 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
1ddc0 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
1ddd0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
1dde0 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
1ddf0 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
1de00 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
1de10 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
1de20 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
1de30 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
1de40 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c  a change..*/.SQL
1de50 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1de60 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1de70 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
1de80 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
1de90 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
1dea0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1deb0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1dec0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
1ded0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
1dee0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1def0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
1df00 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
1df10 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1df20 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1df30 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1df40 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
1df50 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
1df60 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
1df70 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
1df80 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
1df90 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
1dfa0 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
1dfb0 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
1dfc0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
1dfd0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
1dfe0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1dff0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1e000 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
1e010 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1e020 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1e030 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
1e040 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20  QLITE_IGNORE is 
1e050 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b  also used as a [
1e060 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20  SQLITE_ROLLBACK 
1e070 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a  | return code].*
1e080 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  * from the [sqli
1e090 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
1e0a0 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63  lict()] interfac
1e0b0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
1e0c0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
1e0d0 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
1e0e0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
1e0f0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
1e100 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
1e110 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
1e120 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
1e130 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
1e140 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
1e150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1e160 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
1e170 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1e180 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1e190 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
1e1a0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
1e1b0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1e1c0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
1e1d0 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
1e1e0 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
1e1f0 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
1e200 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1e210 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1e220 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1e230 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
1e240 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
1e250 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
1e260 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
1e270 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
1e280 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
1e290 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
1e2a0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e2b0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
1e2c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
1e2d0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
1e2e0 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
1e2f0 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
1e300 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
1e310 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
1e320 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1e330 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
1e340 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
1e350 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
1e360 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
1e370 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
1e380 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
1e390 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
1e3a0 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
1e3b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1e3c0 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
1e3d0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
1e3e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e3f0 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
1e400 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
1e410 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
1e420 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
1e430 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
1e440 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
1e450 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1e460 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
1e470 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
1e480 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
1e490 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
1e4a0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1e4b0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
1e4c0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
1e4d0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
1e4e0 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
1e4f0 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
1e500 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
1e510 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
1e520 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e530 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
1e540 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
1e550 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
1e560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e570 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
1e580 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
1e590 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1e5a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1e5b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1e5c0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
1e5d0 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
1e5e0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1e5f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e600 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1e610 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
1e620 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
1e630 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1e640 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1e650 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1e660 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
1e670 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
1e680 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1e690 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e6a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1e6b0 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
1e6c0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
1e6d0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1e6e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1e6f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1e700 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
1e710 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
1e720 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1e730 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e740 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1e750 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1e760 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
1e770 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1e780 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1e790 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1e7a0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
1e7b0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1e7c0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1e7d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e7e0 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
1e7f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
1e800 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1e810 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1e820 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e830 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
1e840 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
1e850 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1e860 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1e870 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e880 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
1e890 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
1e8a0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1e8b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e8c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e8d0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
1e8e0 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
1e8f0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1e900 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1e910 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e920 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
1e930 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
1e940 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e950 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e960 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e970 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
1e980 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
1e990 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1e9a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e9b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e9c0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
1e9d0 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
1e9e0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1e9f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1ea00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ea10 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
1ea20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
1ea30 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1ea40 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1ea50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ea60 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
1ea70 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
1ea80 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1ea90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1eaa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1eab0 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
1eac0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
1ead0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1eae0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1eaf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
1eb00 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
1eb10 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
1eb20 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
1eb30 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
1eb40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
1eb50 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1eb60 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
1eb70 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
1eb80 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1eb90 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
1eba0 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
1ebb0 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
1ebc0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
1ebd0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ebe0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
1ebf0 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
1ec00 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
1ec10 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
1ec20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ec30 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
1ec40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1ec50 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1ec60 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1ec70 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1ec80 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
1ec90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
1eca0 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
1ecb0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ecc0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ecd0 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
1ece0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
1ecf0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
1ed00 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
1ed10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ed20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
1ed30 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
1ed40 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1ed50 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
1ed60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ed70 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
1ed80 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
1ed90 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1eda0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1edb0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1edc0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
1edd0 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
1ede0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1edf0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1ee00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ee10 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
1ee20 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
1ee30 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ee40 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
1ee50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ee60 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
1ee70 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
1ee80 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ee90 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1eea0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1eeb0 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
1eec0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
1eed0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
1eee0 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
1eef0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ef00 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
1ef10 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
1ef20 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
1ef30 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
1ef40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ef50 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
1ef60 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
1ef70 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
1ef80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ef90 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
1efa0 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
1efb0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1efc0 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
1efd0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
1efe0 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
1eff0 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
1f000 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
1f010 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
1f020 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1f030 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1f040 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1f050 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1f060 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
1f070 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
1f080 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
1f090 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1f0a0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
1f0b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f0c0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
1f0d0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1f0e0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
1f0f0 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
1f100 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
1f110 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1f120 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
1f130 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
1f140 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
1f150 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
1f160 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
1f170 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
1f180 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
1f190 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
1f1a0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
1f1b0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
1f1c0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
1f1d0 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
1f1e0 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
1f1f0 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
1f200 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ger.)^.**.** The
1f210 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53   [SQLITE_TRACE_S
1f220 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  IZE_LIMIT] compi
1f230 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63  le-time option c
1f240 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69  an be used to li
1f250 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74  mit.** the lengt
1f260 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61  h of [bound para
1f270 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e  meter] expansion
1f280 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f   in the output o
1f290 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  f sqlite3_trace(
1f2a0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )..**.** ^The ca
1f2b0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1f2c0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1f2d0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
1f2e0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
1f2f0 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
1f300 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
1f310 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
1f320 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
1f330 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
1f340 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
1f350 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
1f360 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
1f370 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
1f380 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
1f390 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
1f3a0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1f3b0 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
1f3c0 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
1f3d0 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
1f3e0 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
1f3f0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
1f400 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
1f410 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
1f420 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
1f430 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
1f440 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
1f450 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
1f460 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
1f470 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1f480 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
1f490 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
1f4a0 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
1f4b0 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
1f4c0 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  k.  The.** sqlit
1f4d0 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e  e3_profile() fun
1f4e0 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ction is conside
1f4f0 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
1f500 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65   and is.** subje
1f510 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
1f520 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
1f530 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
1f540 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
1f550 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
1f560 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
1f570 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
1f580 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
1f590 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
1f5a0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
1f5b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
1f5c0 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
1f5d0 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
1f5e0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1f5f0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
1f600 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
1f610 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
1f620 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
1f630 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
1f640 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
1f650 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
1f660 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
1f670 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
1f680 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
1f690 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
1f6a0 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
1f6b0 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
1f6c0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
1f6d0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
1f6e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
1f6f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
1f700 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
1f710 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f720 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
1f730 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
1f740 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
1f750 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
1f760 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
1f770 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
1f780 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
1f790 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
1f7a0 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
1f7b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1f7c0 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
1f7d0 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
1f7e0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
1f7f0 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20  the approximate 
1f800 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
1f810 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
1f820 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
1f830 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
1f840 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
1f850 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
1f860 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
1f870 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c  k X.  ^If N is l
1f880 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65  ess than one the
1f890 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a  n the progress.*
1f8a0 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73  * handler is dis
1f8b0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  abled..**.** ^On
1f8c0 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
1f8d0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
1f8e0 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
1f8f0 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
1f900 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f910 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
1f920 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
1f930 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
1f940 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
1f950 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
1f960 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
1f970 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
1f980 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
1f990 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1f9a0 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
1f9b0 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
1f9c0 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
1f9d0 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
1f9e0 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
1f9f0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
1fa00 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1fa10 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
1fa20 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
1fa30 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
1fa40 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
1fa50 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
1fa60 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
1fa70 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
1fa80 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
1fa90 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1faa0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
1fab0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
1fac0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1fad0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1fae0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1faf0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
1fb00 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
1fb10 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
1fb20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1fb30 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
1fb40 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
1fb50 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
1fb60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1fb70 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
1fb80 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
1fb90 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
1fba0 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f  h..**.*/.SQLITE_
1fbb0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
1fbc0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
1fbd0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
1fbe0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
1fbf0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1fc00 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
1fc10 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
1fc20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
1fc30 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1fc40 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
1fc50 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73  database file as
1fc60 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
1fc70 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  e .** filename a
1fc80 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
1fc90 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
1fca0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
1fcb0 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
1fcc0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1fcd0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
1fce0 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
1fcf0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
1fd00 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
1fd10 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
1fd20 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
1fd30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
1fd40 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
1fd50 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
1fd60 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
1fd70 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
1fd80 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
1fd90 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
1fda0 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
1fdb0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
1fdc0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1fdd0 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
1fde0 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
1fdf0 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
1fe00 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
1fe10 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
1fe20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
1fe30 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
1fe40 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
1fe50 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
1fe60 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
1fe70 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
1fe80 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
1fe90 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
1fea0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
1feb0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
1fec0 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
1fed0 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
1fee0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1fef0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
1ff00 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
1ff10 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
1ff20 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
1ff30 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
1ff40 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
1ff50 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
1ff60 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
1ff70 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
1ff80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
1ff90 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
1ffa0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69   the database wi
1ffb0 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a  ll be UTF-8 if.*
1ffc0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1ffd0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
1ffe0 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
1fff0 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e  and.** UTF-16 in
20000 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
20010 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65   order if sqlite
20020 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73  3_open16() is us
20030 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  ed..**.** Whethe
20040 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
20050 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
20060 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
20070 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
20080 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
20090 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
200a0 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
200b0 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
200c0 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
200d0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
200e0 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
200f0 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
20100 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
20110 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
20120 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
20130 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
20140 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
20150 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
20160 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
20170 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
20180 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
20190 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
201a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
201b0 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
201c0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
201d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
201e0 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
201f0 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
20200 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
20210 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
20220 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
20230 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
20240 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
20250 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
20260 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
20270 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b  AREDCACHE],.** [
20280 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
20290 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f  ATECACHE], and/o
202a0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  r [SQLITE_OPEN_U
202b0 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  RI] flags:)^.**.
202c0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
202d0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
202e0 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
202f0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
20300 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
20310 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
20320 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
20330 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
20340 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
20350 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
20360 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
20370 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
20380 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
20390 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
203a0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
203b0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
203c0 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
203d0 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
203e0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
203f0 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
20400 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
20410 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
20420 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
20430 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
20440 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
20450 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
20460 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
20470 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
20480 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
20490 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
204a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
204b0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
204c0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
204d0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
204e0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
204f0 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69  and is created i
20500 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
20510 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
20520 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
20530 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
20540 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
20550 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
20560 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
20570 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
20580 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
20590 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
205a0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
205b0 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
205c0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
205d0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
205e0 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  ve optionally co
205f0 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65  mbined with othe
20600 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  r.** [SQLITE_OPE
20610 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c  N_READONLY | SQL
20620 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d  ITE_OPEN_* bits]
20630 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
20640 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
20650 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
20660 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
20670 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
20680 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
20690 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
206a0 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
206b0 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
206c0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
206d0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
206e0 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
206f0 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
20700 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
20710 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
20720 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
20730 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
20740 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
20750 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
20760 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20770 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
20780 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
20790 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
207a0 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
207b0 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
207c0 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
207d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
207e0 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
207f0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
20800 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
20810 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
20820 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20830 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
20840 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
20850 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
20860 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
20870 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
20880 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
20890 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
208a0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
208b0 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
208c0 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
208d0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
208e0 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
208f0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20900 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
20910 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
20920 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
20930 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
20940 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
20950 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
20960 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
20970 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
20980 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
20990 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
209a0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
209b0 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
209c0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
209d0 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
209e0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
209f0 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
20a00 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
20a10 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
20a20 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
20a30 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
20a40 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
20a50 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
20a60 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
20a70 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
20a80 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
20a90 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
20aa0 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
20ab0 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
20ac0 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
20ad0 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
20ae0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
20af0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
20b00 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
20b10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
20b20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
20b30 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
20b40 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
20b50 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
20b60 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
20b70 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
20b80 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
20b90 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
20ba0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
20bb0 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
20bc0 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
20bd0 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
20be0 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
20bf0 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
20c00 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
20c10 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
20c20 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
20c30 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
20c40 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
20c50 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
20c60 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
20c70 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
20c80 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
20c90 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
20ca0 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
20cb0 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
20cc0 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
20cd0 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
20ce0 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
20cf0 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
20d00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20d10 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
20d20 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   [[URI filenames
20d30 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
20d40 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c  ()]] <h3>URI Fil
20d50 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  enames</h3>.**.*
20d60 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e  * ^If [URI filen
20d70 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74  ame] interpretat
20d80 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  ion is enabled, 
20d90 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  and the filename
20da0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67   argument.** beg
20db0 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22  ins with "file:"
20dc0 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e  , then the filen
20dd0 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74  ame is interpret
20de0 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52  ed as a URI. ^UR
20df0 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e  I.** filename in
20e00 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
20e10 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b  enabled if the [
20e20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
20e30 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20   flag is.** set 
20e40 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  in the fourth ar
20e50 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
20e60 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20  3_open_v2(), or 
20e70 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65  if it has.** bee
20e80 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c  n enabled global
20e90 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ly using the [SQ
20ea0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
20eb0 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65   option with the
20ec0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
20ed0 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72  fig()] method or
20ee0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
20ef0 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65  USE_URI] compile
20f00 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
20f10 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65   As of SQLite ve
20f20 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49  rsion 3.7.7, URI
20f30 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
20f40 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e  retation is turn
20f50 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66  ed off.** by def
20f60 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65  ault, but future
20f70 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
20f80 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65  ite might enable
20f90 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   URI filename.**
20fa0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
20fb0 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65  by default.  See
20fc0 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   "[URI filenames
20fd0 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ]" for additiona
20fe0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
20ff0 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65  ..**.** URI file
21000 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64  names are parsed
21010 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46   according to RF
21020 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20  C 3986. ^If the 
21030 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a  URI contains an.
21040 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68  ** authority, th
21050 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69  en it must be ei
21060 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74  ther an empty st
21070 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69  ring or the stri
21080 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73  ng .** "localhos
21090 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68  t". ^If the auth
210a0 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20  ority is not an 
210b0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
210c0 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20  "localhost", an 
210d0 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74  .** error is ret
210e0 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c  urned to the cal
210f0 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65  ler. ^The fragme
21100 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  nt component of 
21110 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72  a URI, if .** pr
21120 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65  esent, is ignore
21130 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
21140 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63   uses the path c
21150 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20  omponent of the 
21160 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20  URI as the name 
21170 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65  of the disk file
21180 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69  .** which contai
21190 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ns the database.
211a0 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65   ^If the path be
211b0 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20  gins with a '/' 
211c0 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74  character, .** t
211d0 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70  hen it is interp
211e0 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f  reted as an abso
211f0 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74  lute path. ^If t
21200 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74  he path does not
21210 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20   begin .** with 
21220 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74  a '/' (meaning t
21230 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74  hat the authorit
21240 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69  y section is omi
21250 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52  tted from the UR
21260 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70  I).** then the p
21270 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ath is interpret
21280 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65  ed as a relative
21290 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77   path. .** ^On w
212a0 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73  indows, the firs
212b0 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
212c0 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20  n absolute path 
212d0 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73  .** is a drive s
212e0 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e  pecification (e.
212f0 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20  g. "C:")..**.** 
21300 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79  [[core URI query
21310 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a   parameters]].**
21320 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   The query compo
21330 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61  nent of a URI ma
21340 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65  y contain parame
21350 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e  ters that are in
21360 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74  terpreted.** eit
21370 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74  her by SQLite it
21380 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56  self, or by a [V
21390 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20  FS | custom VFS 
213a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e  implementation].
213b0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
213c0 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77  prets the follow
213d0 69 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 20  ing three query 
213e0 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
213f0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
21400 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
21410 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
21420 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
21430 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
21440 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
21450 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
21460 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
21470 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
21480 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
21490 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
214a0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
214b0 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
214c0 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
214d0 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
214e0 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
214f0 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
21500 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
21510 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
21520 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
21530 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
21540 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
21550 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
21560 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
21570 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
21580 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
21590 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
215a0 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
215b0 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
215c0 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
215d0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
215e0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
215f0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
21600 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
21610 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
21620 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
21630 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
21640 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
21650 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
21660 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
21670 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
21680 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
21690 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
216a0 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
216b0 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
216c0 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
216d0 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
216e0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
216f0 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
21700 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
21710 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
21720 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
21730 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
21740 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
21750 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
21760 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
21770 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
21780 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
21790 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
217a0 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
217b0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
217c0 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
217d0 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
217e0 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
217f0 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
21800 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
21810 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
21820 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
21830 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
21840 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
21850 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
21860 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
21870 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
21880 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
21890 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
218a0 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
218b0 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
218c0 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
218d0 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
218e0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
218f0 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
21900 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
21910 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
21920 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
21930 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
21940 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
21950 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
21960 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
21970 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
21980 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
21990 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
219a0 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
219b0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
219c0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
219d0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
219e0 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
219f0 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
21a00 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
21a10 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
21a20 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
21a30 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
21a40 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
21a50 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
21a60 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
21a70 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
21a80 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
21a90 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
21aa0 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
21ab0 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
21ac0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
21ad0 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
21ae0 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
21af0 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
21b00 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
21b10 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
21b20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
21b30 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
21b40 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
21b50 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
21b60 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
21b70 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
21b80 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
21b90 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
21ba0 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
21bb0 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
21bc0 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
21bd0 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
21be0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
21bf0 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
21c00 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
21c10 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c  HE flag..** </ul
21c20 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79  >.**.** ^Specify
21c30 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70  ing an unknown p
21c40 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
21c50 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
21c60 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20  of a URI is not 
21c70 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75  an.** error.  Fu
21c80 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
21c90 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e   SQLite might un
21ca0 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f  derstand additio
21cb0 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  nal query.** par
21cc0 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b  ameters.  See "[
21cd0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
21ce0 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65   with special me
21cf0 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d  aning to SQLite]
21d00 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  " for.** additio
21d10 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
21d20 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
21d30 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d  ename examples]]
21d40 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d   <h3>URI filenam
21d50 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a  e examples</h3>.
21d60 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  **.** <table bor
21d70 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65  der="1" align=ce
21d80 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67  nter cellpadding
21d90 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  =5>.** <tr><th> 
21da0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74  URI filenames <t
21db0 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74  h> Results.** <t
21dc0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
21dd0 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
21de0 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66        Open the f
21df0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
21e00 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
21e10 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  ectory..** <tr><
21e20 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
21e30 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a  red/data.db<br>.
21e40 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
21e50 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  :///home/fred/da
21e60 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20  ta.db <br> .**  
21e70 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c          file://l
21e80 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72  ocalhost/home/fr
21e90 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
21ea0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
21eb0 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62    Open the datab
21ec0 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  ase file "/home/
21ed0 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a  fred/data.db"..*
21ee0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
21ef0 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f  //darkstar/home/
21f00 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64  fred/data.db <td
21f10 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
21f20 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74  n error. "darkst
21f30 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63  ar" is not a rec
21f40 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74  ognized authorit
21f50 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74  y..** <tr><td st
21f60 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65  yle="white-space
21f70 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20  :nowrap"> .**   
21f80 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43         file:///C
21f90 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e  :/Documents%20an
21fa0 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65  d%20Settings/fre
21fb0 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64  d/Desktop/data.d
21fc0 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69  b.**     <td> Wi
21fd0 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e  ndows only: Open
21fe0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
21ff0 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65  db" on fred's de
22000 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a  sktop on drive.*
22010 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e  *          C:. N
22020 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30  ote that the %20
22030 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69   escaping in thi
22040 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74  s example is not
22050 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20   strictly .**   
22060 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79         necessary
22070 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74   - space charact
22080 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ers can be used 
22090 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20  literally.**    
220a0 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c        in URI fil
220b0 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c  enames..** <tr><
220c0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
220d0 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70  ?mode=ro&cache=p
220e0 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20  rivate <td> .** 
220f0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
22100 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
22110 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
22120 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f  ctory for read-o
22130 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20  nly access..**  
22140 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65          Regardle
22150 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
22160 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68   not shared-cach
22170 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65  e mode is enable
22180 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
22190 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20   default, use a 
221a0 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a  private cache..*
221b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
221c0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
221d0 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f  db?vfs=unix-nolo
221e0 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  ck <td>.**      
221f0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
22200 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
22210 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
22220 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f  ial VFS "unix-no
22230 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  lock"..** <tr><t
22240 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
22250 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74  mode=readonly <t
22260 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
22270 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f  An error. "reado
22280 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61  nly" is not a va
22290 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74  lid option for t
222a0 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65  he "mode" parame
222b0 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ter..** </table>
222c0 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61  .**.** ^URI hexa
222d0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
222e0 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61  equences (%HH) a
222f0 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74  re supported wit
22300 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64  hin the path and
22310 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  .** query compon
22320 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41  ents of a URI. A
22330 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
22340 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e  ape sequence con
22350 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65  sists of a.** pe
22360 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22  rcent sign - "%"
22370 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65   - followed by e
22380 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64  xactly two hexad
22390 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a  ecimal digits .*
223a0 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20  * specifying an 
223b0 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65  octet value. ^Be
223c0 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72  fore the path or
223d0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
223e0 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69  s of a.** URI fi
223f0 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72  lename are inter
22400 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65  preted, they are
22410 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
22420 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a  TF-8 and all .**
22430 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
22440 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65  ape sequences re
22450 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67  placed by a sing
22460 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69  le byte containi
22470 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73  ng the.** corres
22480 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49  ponding octet. I
22490 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67  f this process g
224a0 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61  enerates an inva
224b0 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  lid UTF-8 encodi
224c0 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  ng,.** the resul
224d0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
224e0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
224f0 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
22500 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
22510 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
22520 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
22530 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
22540 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
22550 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
22560 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
22570 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
22580 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
22590 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
225a0 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
225b0 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
225c0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
225d0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
225e0 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
225f0 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
22600 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
22610 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
22620 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
22630 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
22640 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
22650 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
22660 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
22670 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
22680 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
22690 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
226a0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
226b0 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65  v2().  Otherwise
226c0 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
226d0 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
226e0 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
226f0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
22700 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65  y fail..**.** Se
22710 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
22720 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d  _temp_directory]
22730 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
22740 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
22750 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
22760 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
22770 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
22780 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
22790 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
227a0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
227b0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
227c0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
227d0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
227e0 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
227f0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
22800 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
22810 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
22820 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
22830 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
22840 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
22850 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
22860 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
22870 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
22880 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
22890 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
228a0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
228b0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
228c0 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
228d0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
228e0 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
228f0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
22900 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
22910 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
22920 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
22930 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
22940 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
22950 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
22960 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
22970 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
22980 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
22990 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
229a0 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
229b0 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
229c0 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
229d0 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
229e0 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
229f0 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
22a00 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
22a10 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
22a20 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
22a30 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
22a40 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
22a50 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
22a60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
22a70 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
22a80 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
22a90 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
22aa0 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
22ab0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
22ac0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
22ad0 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
22ae0 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
22af0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
22b00 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
22b10 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
22b20 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
22b30 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
22b40 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
22b50 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
22b60 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
22b70 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
22b80 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
22b90 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
22ba0 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
22bb0 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
22bc0 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
22bd0 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
22be0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
22bf0 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
22c00 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
22c10 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
22c20 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
22c30 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
22c40 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
22c50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
22c60 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
22c70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
22c80 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
22c90 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
22ca0 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
22cb0 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
22cc0 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
22cd0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
22ce0 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
22cf0 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
22d00 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
22d10 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
22d20 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
22d30 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
22d40 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
22d50 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
22d60 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
22d70 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
22d80 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
22d90 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
22da0 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
22db0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
22dc0 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
22dd0 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
22de0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
22df0 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
22e00 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
22e10 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
22e20 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
22e30 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
22e40 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
22e50 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
22e60 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
22e70 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
22e80 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
22e90 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
22ea0 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
22eb0 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
22ec0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
22ed0 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
22ee0 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
22ef0 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
22f00 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
22f10 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
22f20 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
22f30 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
22f40 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
22f50 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
22f60 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
22f70 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
22f80 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
22f90 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
22fa0 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
22fb0 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
22fc0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
22fd0 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
22fe0 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
22ff0 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
23000 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
23010 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
23020 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
23030 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
23040 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
23050 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
23060 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
23070 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
23080 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
23090 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
230a0 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
230b0 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
230c0 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
230d0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
230e0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
230f0 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
23100 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
23110 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
23120 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
23130 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
23140 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
23150 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
23160 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
23170 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
23180 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
23190 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
231a0 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49  r *zParam);.SQLI
231b0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
231c0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63  e3_uri_boolean(c
231d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
231e0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
231f0 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75  aram, int bDefau
23200 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  lt);.SQLITE_API 
23210 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
23220 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
23230 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e  const char*, con
23240 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
23250 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a  3_int64);.../*.*
23260 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
23270 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
23280 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
23290 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
232a0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
232b0 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
232c0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
232d0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
232e0 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
232f0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
23300 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
23310 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
23320 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
23330 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23340 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
23350 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
23360 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
23370 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
23380 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
23390 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
233a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
233b0 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
233c0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
233d0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
233e0 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
233f0 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
23400 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
23410 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
23420 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
23430 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
23440 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
23450 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
23460 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
23470 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
23480 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
23490 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
234a0 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
234b0 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
234c0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
234d0 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
234e0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
234f0 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
23500 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
23510 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
23520 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
23530 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
23540 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
23550 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
23560 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
23570 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
23580 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
23590 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
235a0 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
235b0 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
235c0 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
235d0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
235e0 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
235f0 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
23600 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ions.)^.**.** ^T
23610 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  he sqlite3_errst
23620 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  r() interface re
23630 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73  turns the Englis
23640 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a  h-language text.
23650 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65  ** that describe
23660 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f  s the [result co
23670 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a  de], as UTF-8..*
23680 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
23690 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
236a0 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
236b0 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
236c0 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f  y.** and must no
236d0 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68  t be freed by th
236e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e  e application)^.
236f0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
23700 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
23710 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
23720 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
23730 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
23740 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
23750 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
23760 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
23770 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
23780 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
23790 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
237a0 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
237b0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
237c0 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
237d0 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
237e0 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
237f0 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
23800 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
23810 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
23820 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
23830 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
23840 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
23850 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
23860 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
23870 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
23880 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
23890 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
238a0 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
238b0 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
238c0 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
238d0 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
238e0 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
238f0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
23900 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
23910 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
23920 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
23930 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
23940 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
23950 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
23960 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
23970 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
23980 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
23990 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
239a0 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
239b0 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
239c0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
239d0 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
239e0 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
239f0 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
23a00 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
23a10 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49   be set..*/.SQLI
23a20 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
23a30 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
23a40 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f  e3 *db);.SQLITE_
23a50 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
23a60 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
23a70 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53  (sqlite3 *db);.S
23a80 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
23a90 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
23aa0 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
23ab0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
23ac0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
23ad0 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
23ae0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
23af0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
23b00 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a  3_errstr(int);..
23b10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23b20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
23b30 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
23b40 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
23b50 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
23b60 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
23b70 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
23b80 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
23b90 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
23ba0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
23bb0 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
23bc0 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f  is variously kno
23bd0 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65  wn as a "prepare
23be0 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  d statement" or 
23bf0 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53  a.** "compiled S
23c00 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  QL statement" or
23c10 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74   simply as a "st
23c20 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20  atement"..**.** 
23c30 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
23c40 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
23c50 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
23c60 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
23c70 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
23c80 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
23c90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
23ca0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
23cb0 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
23cc0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
23cd0 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
23ce0 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   [host parameter
23cf0 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
23d00 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
23d10 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
23d20 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
23d30 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
23d40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23d50 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
23d60 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
23d70 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  et the statement
23d80 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
23d90 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
23da0 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
23db0 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
23dc0 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
23dd0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
23de0 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
23df0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
23e00 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
23e10 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65  </ol>.**.** Refe
23e20 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69  r to documentati
23e30 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
23e40 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66   methods above f
23e50 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
23e60 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
23e70 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
23e80 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
23e90 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
23ea0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
23eb0 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a  time Limits.**.*
23ec0 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
23ed0 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
23ee0 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
23ef0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
23f00 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
23f10 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
23f20 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
23f30 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
23f40 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
23f50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23f60 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
23f70 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
23f80 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
23f90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
23fa0 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
23fb0 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
23fc0 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
23fd0 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
23fe0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
23ff0 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
24000 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
24010 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
24020 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
24030 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
24040 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
24050 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
24060 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
24070 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
24080 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
24090 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
240a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
240b0 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
240c0 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
240d0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
240e0 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
240f0 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
24100 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
24110 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
24120 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
24130 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
24140 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
24150 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
24160 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
24170 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
24180 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
24190 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
241a0 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
241b0 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
241c0 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
241d0 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
241e0 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
241f0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
24200 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
24210 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
24220 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
24230 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
24240 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
24250 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
24260 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
24270 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
24280 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
24290 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
242a0 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
242b0 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
242c0 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
242d0 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
242e0 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
242f0 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
24300 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
24310 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
24320 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
24330 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
24340 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
24350 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
24360 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
24370 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
24380 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
24390 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
243a0 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
243b0 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
243c0 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
243d0 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
243e0 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
243f0 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
24400 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
24410 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
24420 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
24430 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
24440 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
24450 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
24460 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
24470 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
24480 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
24490 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
244a0 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
244b0 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
244c0 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
244d0 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
244e0 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
244f0 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
24500 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
24510 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
24520 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
24530 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
24540 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
24550 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
24560 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
24570 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
24580 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
24590 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
245a0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
245b0 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
245c0 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
245d0 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
245e0 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
245f0 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
24600 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
24610 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
24620 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
24630 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
24640 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
24650 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ases..*/.SQLITE_
24660 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
24670 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
24680 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
24690 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
246a0 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
246b0 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
246c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
246d0 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
246e0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
246f0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
24700 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
24710 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
24720 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
24730 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
24740 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
24750 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
24760 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
24770 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
24780 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
24790 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
247a0 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
247b0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
247c0 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
247d0 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
247e0 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
247f0 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
24800 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
24810 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
24820 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
24830 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
24840 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
24850 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
24860 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
24870 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
24880 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
24890 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
248a0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
248b0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
248c0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
248d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
248e0 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
248f0 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
24900 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
24910 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
24920 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
24930 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
24940 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
24950 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
24960 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
24970 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
24980 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
24990 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
249a0 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
249b0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
249c0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
249d0 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
249e0 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
249f0 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
24a00 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
24a10 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
24a20 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
24a30 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
24a40 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
24a50 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
24a60 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
24a70 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
24a80 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
24a90 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
24aa0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
24ab0 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
24ac0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
24ad0 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
24ae0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
24af0 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
24b00 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
24b10 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
24b20 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
24b30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
24b40 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
24b50 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
24b60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
24b70 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
24b80 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
24b90 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
24ba0 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
24bb0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
24bc0 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
24bd0 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
24be0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
24bf0 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
24c00 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
24c10 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
24c20 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
24c30 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
24c40 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
24c50 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
24c60 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
24c70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
24c80 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
24c90 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
24ca0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
24cb0 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
24cc0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
24cd0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
24ce0 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
24cf0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
24d00 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
24d10 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
24d20 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
24d30 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
24d40 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
24d50 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
24d60 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
24d70 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
24d80 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
24d90 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
24da0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
24db0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
24dc0 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
24dd0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
24de0 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
24df0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
24e00 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
24e10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
24e20 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
24e30 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
24e40 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
24e50 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
24e60 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
24e70 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
24e80 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
24e90 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
24ea0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
24eb0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
24ec0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
24ed0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
24ee0 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
24ef0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
24f00 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
24f10 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
24f20 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
24f30 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
24f40 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
24f50 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
24f60 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
24f70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
24f80 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
24f90 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
24fa0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
24fb0 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
24fc0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
24fd0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
24fe0 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
24ff0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
25000 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
25010 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
25020 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
25030 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25040 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
25050 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
25060 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25070 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
25080 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
25090 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
250a0 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
250b0 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
250c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
250d0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
250e0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
250f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25100 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
25110 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
25120 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
25130 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
25140 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
25150 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25160 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
25170 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
25180 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
25190 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
251a0 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
251b0 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
251c0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
251d0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
251e0 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
251f0 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
25200 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
25210 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
25220 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
25230 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
25240 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
25250 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
25260 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
25270 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
25280 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
25290 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
252a0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
252b0 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
252c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
252d0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
252e0 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
252f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
25300 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
25310 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
25320 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
25330 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
25340 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
25350 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
25360 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
25370 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
25380 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
25390 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
253a0 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
253b0 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
253c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
253d0 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
253e0 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
253f0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
25400 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
25410 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
25420 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
25430 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
25440 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
25450 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
25460 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
25470 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
25480 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
25490 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
254a0 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
254b0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
254c0 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
254d0 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
254e0 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
254f0 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
25500 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
25510 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
25520 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
25530 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
25540 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
25550 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
25560 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
25570 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
25580 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
25590 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
255a0 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
255b0 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
255c0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
255d0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
255e0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
255f0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
25600 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
25610 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
25620 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
25630 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73  minator bytes as
25640 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69   this saves SQLi
25650 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74  te from having t
25660 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79  o.** make a copy
25670 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   of the input st
25680 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
25690 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
256a0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
256b0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
256c0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
256d0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
256e0 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
256f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
25700 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
25710 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
25720 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
25730 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
25740 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
25750 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
25760 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
25770 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
25780 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
25790 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
257a0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
257b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
257c0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
257d0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
257e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
257f0 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
25800 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
25810 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
25820 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
25830 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
25840 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
25850 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
25860 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
25870 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
25880 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
25890 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
258a0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
258b0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
258c0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
258d0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
258e0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
258f0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
25900 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
25910 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
25920 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
25930 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
25940 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
25950 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
25960 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
25970 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
25980 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
25990 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
259a0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
259b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
259c0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
259d0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
259e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
259f0 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
25a00 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
25a10 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
25a20 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
25a30 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
25a40 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
25a50 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
25a60 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
25a70 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
25a80 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
25a90 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
25aa0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
25ab0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
25ac0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
25ad0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
25ae0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
25af0 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
25b00 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
25b10 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
25b20 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
25b30 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
25b40 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
25b50 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
25b60 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
25b70 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
25b80 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
25b90 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
25ba0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
25bb0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
25bc0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
25bd0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
25be0 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
25bf0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
25c00 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
25c10 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
25c20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
25c30 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
25c40 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53  n. As many as [S
25c50 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41  QLITE_MAX_SCHEMA
25c60 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69  _RETRY].** retri
25c70 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65  es will occur be
25c80 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65  fore sqlite3_ste
25c90 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64  p() gives up and
25ca0 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
25cb0 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  r..** </li>.**.*
25cc0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
25cd0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
25ce0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
25cf0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
25d00 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
25d10 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
25d20 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
25d30 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
25d40 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
25d50 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
25d60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
25d70 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
25d80 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
25d90 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
25da0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
25db0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
25dc0 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
25dd0 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
25de0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
25df0 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
25e00 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
25e10 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
25e20 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
25e30 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
25e40 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
25e50 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
25e60 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
25e70 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
25e80 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
25e90 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
25ea0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
25eb0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
25ec0 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
25ed0 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
25ee0 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
25ef0 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
25f00 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
25f10 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
25f20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
25f30 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
25f40 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
25f50 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
25f60 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
25f70 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
25f80 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
25f90 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
25fa0 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
25fb0 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
25fc0 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
25fd0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
25fe0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
25ff0 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
26000 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
26010 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
26020 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
26030 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
26040 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
26050 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
26060 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
26070 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
26080 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
26090 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
260a0 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
260b0 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
260c0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
260d0 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
260e0 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
260f0 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
26100 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
26110 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
26120 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
26130 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
26140 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
26150 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
26160 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
26170 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
26180 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
26190 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
261a0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
261b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
261c0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
261d0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
261e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
261f0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
26200 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
26210 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
26220 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
26230 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
26240 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
26250 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
26260 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
26270 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
26280 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
26290 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
262a0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
262b0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
262c0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
262d0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
262e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
262f0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
26300 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
26310 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
26320 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
26330 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
26340 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
26350 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
26360 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
26370 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
26380 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
26390 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
263a0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
263b0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
263c0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
263d0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
263e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
263f0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
26400 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
26410 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
26420 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
26430 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
26440 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
26450 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
26460 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
26470 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
26480 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
26490 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
264a0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
264b0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
264c0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
264d0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
264e0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
264f0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
26500 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
26510 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
26520 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
26530 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
26540 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
26550 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
26560 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
26570 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
26580 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
26590 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
265a0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
265b0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
265c0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
265d0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
265e0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
265f0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
26600 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
26610 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
26620 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
26630 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
26640 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
26650 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
26660 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
26670 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
26680 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
26690 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
266a0 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
266b0 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  L.**.** ^This in
266c0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
266d0 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
266e0 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
266f0 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
26700 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
26710 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
26720 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
26730 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
26740 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
26750 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
26760 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
26770 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
26780 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
26790 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
267a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
267b0 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
267c0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
267d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
267e0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
267f0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69  QL Statement Wri
26800 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65  tes The Database
26810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
26820 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
26830 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
26840 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
26850 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
26860 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
26870 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26880 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
26890 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
268a0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
268b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
268c0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
268d0 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
268e0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
268f0 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
26900 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
26910 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
26920 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
26930 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
26940 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
26950 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
26960 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
26970 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
26980 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
26990 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
269a0 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
269b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
269c0 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
269d0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
269e0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
269f0 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
26a00 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
26a10 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
26a20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
26a30 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
26a40 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
26a50 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
26a60 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
26a70 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
26a80 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
26a90 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
26aa0 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
26ab0 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
26ac0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
26ad0 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
26ae0 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
26af0 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
26b00 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
26b10 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
26b20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
26b30 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
26b40 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
26b50 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
26b60 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
26b70 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
26b80 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
26b90 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
26ba0 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
26bb0 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
26bc0 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
26bd0 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
26be0 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
26bf0 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
26c00 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
26c10 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
26c20 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
26c30 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
26c40 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
26c50 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
26c60 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
26c70 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
26c80 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
26c90 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
26ca0 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
26cb0 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
26cc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
26cd0 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
26ce0 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
26cf0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
26d00 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
26d10 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53  es on disk..*/.S
26d20 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
26d30 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
26d40 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  nly(sqlite3_stmt
26d50 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
26d60 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
26d70 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72  mine If A Prepar
26d80 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73  ed Statement Has
26d90 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a   Been Reset.**.*
26da0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
26db0 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65  tmt_busy(S) inte
26dc0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
26dd0 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
26de0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
26df0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
26e00 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20  as been stepped 
26e10 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73  at least once us
26e20 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
26e30 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61  _step(S)] but ha
26e40 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d  s not run to com
26e50 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68  pletion and/or h
26e60 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20  as not .** been 
26e70 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c  reset using [sql
26e80 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20  ite3_reset(S)]. 
26e90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
26ea0 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e  mt_busy(S).** in
26eb0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
26ec0 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20  false if S is a 
26ed0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
26ee0 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a  f S is not a .**
26ef0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
26f00 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74  d is not a point
26f10 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70  er to a valid [p
26f20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26f30 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68  t].** object, th
26f40 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
26f50 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
26f60 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
26f70 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rable..**.** Thi
26f80 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
26f90 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69  be used in combi
26fa0 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  nation [sqlite3_
26fb0 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20  next_stmt()].** 
26fc0 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72  to locate all pr
26fd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26fe0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
26ff0 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  h a database .**
27000 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
27010 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20   are in need of 
27020 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68  being reset.  Th
27030 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a  is can be used,.
27040 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** for example, 
27050 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f  in diagnostic ro
27060 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68  utines to search
27070 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a   for prepared .*
27080 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  * statements tha
27090 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20  t are holding a 
270a0 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e  transaction open
270b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
270c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
270d0 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74  _busy(sqlite3_st
270e0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
270f0 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c  I3REF: Dynamical
27100 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
27110 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
27120 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
27130 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
27140 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27150 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
27160 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
27170 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27180 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
27190 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
271a0 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
271b0 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
271c0 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
271d0 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
271e0 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
271f0 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20  ues it stores.  
27200 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69  ^Values stored i
27210 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
27220 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62  objects.** can b
27230 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
27240 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
27250 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
27260 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
27270 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
27280 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
27290 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
272a0 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
272b0 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
272c0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
272d0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
272e0 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
272f0 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
27300 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
27310 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
27320 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
27330 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
27340 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
27350 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
27360 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
27370 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
27380 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  es.** whether or
27390 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73   not it requires
273a0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
273b0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  ite3_value..**.*
273c0 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f  * The terms "pro
273d0 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70  tected" and "unp
273e0 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20  rotected" refer 
273f0 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  to whether or no
27400 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20  t.** a mutex is 
27410 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e  held.  An intern
27420 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
27430 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
27440 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
27450 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
27460 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
27470 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
27480 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
27490 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
274a0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
274b0 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
274c0 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
274d0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
274e0 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
274f0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
27500 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
27510 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
27520 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
27530 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
27540 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
27550 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
27560 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
27570 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
27580 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
27590 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
275a0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
275b0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
275c0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
275d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
275e0 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
275f0 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
27600 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
27610 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
27620 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
27630 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
27640 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
27650 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
27660 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
27670 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
27680 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
27690 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
276a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
276b0 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
276c0 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
276d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
276e0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
276f0 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
27700 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
27710 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
27720 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
27730 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
27740 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
27750 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
27760 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27770 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
27780 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
27790 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
277a0 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
277b0 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
277c0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
277d0 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
277e0 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
277f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
27800 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
27810 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
27820 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
27830 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
27840 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
27850 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
27860 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
27870 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
27880 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
27890 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
278a0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
278b0 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
278c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
278d0 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  F: SQL Function 
278e0 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a  Context Object.*
278f0 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
27900 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
27910 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
27920 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
27930 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
27940 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e  ntext object.  ^
27950 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
27960 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
27970 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
27980 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
27990 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
279a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
279b0 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
279c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
279d0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
279e0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
279f0 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
27a00 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
27a10 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
27a20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
27a30 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
27a40 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
27a50 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
27a60 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
27a70 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
27a80 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
27a90 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
27aa0 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
27ab0 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
27ac0 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
27ad0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
27ae0 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
27af0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
27b00 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
27b10 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
27b20 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
27b30 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
27b40 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  d Statements.** 
27b50 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
27b60 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
27b70 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
27b80 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
27b90 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
27ba0 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
27bb0 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
27bc0 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
27bd0 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ing}.**.** ^(In 
27be0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
27bf0 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20  t text input to 
27c00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27c10 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
27c20 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65  ariants,.** lite
27c30 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c  rals may be repl
27c40 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d  aced by a [param
27c50 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68  eter] that match
27c60 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77  es one of follow
27c70 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73  ing.** templates
27c80 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
27c90 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
27ca0 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
27cb0 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56  VVV.** <li>  @VV
27cc0 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  V.** <li>  $VVV.
27cd0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
27ce0 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20  n the templates 
27cf0 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65  above, NNN repre
27d00 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72  sents an integer
27d10 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64   literal,.** and
27d20 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20   VVV represents 
27d30 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  an alphanumeric 
27d40 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e  identifier.)^  ^
27d50 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
27d60 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
27d70 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
27d80 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
27d90 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
27da0 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
27db0 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
27dc0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
27dd0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
27de0 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
27df0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
27e00 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
27e10 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
27e20 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a  tines is always.
27e30 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
27e40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
27e50 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
27e60 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
27e70 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
27e80 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
27e90 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  s..**.** ^The se
27ea0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
27eb0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
27ec0 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
27ed0 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54  to be set..** ^T
27ee0 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
27ef0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
27f00 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57   index of 1.  ^W
27f10 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  hen the same nam
27f20 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ed.** SQL parame
27f30 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65  ter is used more
27f40 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f   than once, seco
27f50 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
27f60 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73  t.** occurrences
27f70 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69   have the same i
27f80 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73  ndex as the firs
27f90 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a  t occurrence..**
27fa0 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20   ^The index for 
27fb0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
27fc0 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
27fd0 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
27fe0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
27ff0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
28000 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
28010 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66   ^The index.** f
28020 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65  or "?NNN" parame
28030 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75  ters is the valu
28040 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68  e of NNN..** ^Th
28050 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
28060 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
28070 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  d the [sqlite3_l
28080 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d  imit()].** param
28090 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d  eter [SQLITE_LIM
280a0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
280b0 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c  ER] (default val
280c0 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20  ue: 999)..**.** 
280d0 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
280e0 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
280f0 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
28100 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
28110 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
28120 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
28130 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
28140 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
28150 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  t16().** or sqli
28160 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
28170 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
28180 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  r then the fourt
28190 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  h parameter.** i
281a0 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68  s ignored and th
281b0 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20  e end result is 
281c0 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69  the same as sqli
281d0 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e  te3_bind_null().
281e0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73  .**.** ^(In thos
281f0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
28200 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
28210 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
28220 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
28230 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
28240 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
28250 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
28260 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
28270 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
28280 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
28290 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
282a0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
282b0 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.)^.** ^If the 
282c0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
282d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
282e0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
282f0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
28300 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
28310 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68   then the length
28320 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
28330 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
28340 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
28350 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
28360 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20  rminator..** If 
28370 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
28380 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
28390 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e  bind_blob() is n
283a0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a  egative, then.**
283b0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
283c0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
283d0 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  f a non-negative
283e0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
283f0 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  r is provided to
28400 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
28410 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  xt().** or sqlit
28420 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
28430 20 74 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d   then that param
28440 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65  eter must be the
28450 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20   byte offset.** 
28460 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
28470 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f  rminator would o
28480 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68  ccur assuming th
28490 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55  e string were NU
284a0 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e  L.** terminated.
284b0 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
284c0 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74  racters occur at
284d0 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65   byte offsets le
284e0 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20  ss than .** the 
284f0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75  value of the fou
28500 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68  rth parameter th
28510 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
28520 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69   string value wi
28530 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d  ll.** contain em
28540 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68  bedded NULs.  Th
28550 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  e result of expr
28560 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e  essions involvin
28570 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74  g strings.** wit
28580 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
28590 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
285a0 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
285b0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
285c0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
285d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
285e0 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
285f0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
28600 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
28610 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
28620 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
28630 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
28640 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
28650 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
28660 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
28670 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
28680 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
28690 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
286a0 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
286b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
286c0 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  ob(),.** sqlite3
286d0 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72  _bind_text(), or
286e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
286f0 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a  xt16() fails.  .
28700 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
28710 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
28720 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
28730 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
28740 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
28750 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
28760 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
28770 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
28780 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
28790 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
287a0 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  o be freed..** ^
287b0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
287c0 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
287d0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
287e0 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
287f0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
28800 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
28810 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
28820 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
28830 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
28840 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
28850 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
28860 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
28870 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
28880 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
28890 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
288a0 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
288b0 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
288c0 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
288d0 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
288e0 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
288f0 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
28900 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
28910 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
28920 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
28930 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
28940 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
28950 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
28960 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
28970 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
28980 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
28990 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
289a0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
289b0 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
289c0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
289d0 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
289e0 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
289f0 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
28a00 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
28a10 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
28a20 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
28a30 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
28a40 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
28a50 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
28a60 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
28a70 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
28a80 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
28a90 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
28aa0 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
28ab0 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
28ac0 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
28ad0 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
28ae0 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
28af0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
28b00 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
28b10 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
28b20 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
28b30 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
28b40 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
28b50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
28b60 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
28b70 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
28b80 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
28b90 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
28ba0 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
28bb0 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
28bc0 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
28bd0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
28be0 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
28bf0 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
28c00 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
28c10 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
28c20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
28c30 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
28c40 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
28c50 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
28c60 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
28c70 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
28c80 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
28c90 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
28ca0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
28cb0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
28cc0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
28cd0 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
28ce0 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
28cf0 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
28d00 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
28d10 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
28d20 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
28d30 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
28d40 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
28d50 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
28d60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
28d70 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
28d80 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
28d90 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
28da0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
28db0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
28dc0 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
28dd0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
28de0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
28df0 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
28e00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28e10 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c  nt, double);.SQL
28e20 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
28e30 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
28e40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
28e50 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
28e60 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
28e70 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
28e80 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
28e90 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c  ite3_int64);.SQL
28ea0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
28eb0 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
28ec0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28ed0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
28ee0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
28ef0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
28f00 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
28f10 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  ar*, int n, void
28f20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
28f30 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
28f40 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
28f50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28f60 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
28f70 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
28f80 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
28f90 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
28fa0 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
28fb0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
28fc0 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
28fd0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
28fe0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
28ff0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
29000 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
29010 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
29020 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
29030 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
29040 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
29050 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
29060 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
29070 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
29080 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
29090 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
290a0 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
290b0 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
290c0 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
290d0 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
290e0 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
290f0 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
29100 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
29110 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
29120 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
29130 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
29140 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
29150 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
29160 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
29170 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
29180 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
29190 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
291a0 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
291b0 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
291c0 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
291d0 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
291e0 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
291f0 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
29200 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
29210 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
29220 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
29230 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
29240 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
29250 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
29260 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
29270 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
29280 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
29290 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
292a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
292b0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
292c0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
292d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
292e0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
292f0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
29300 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29310 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
29320 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
29330 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
29340 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
29350 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29360 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29370 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
29380 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
29390 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
293a0 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
293b0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
293c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
293d0 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
293e0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
293f0 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
29400 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
29410 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
29420 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
29430 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
29440 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
29450 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
29460 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
29470 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
29480 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
29490 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
294a0 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
294b0 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
294c0 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
294d0 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
294e0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
294f0 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
29500 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
29510 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
29520 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
29530 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
29540 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
29550 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
29560 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
29570 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
29580 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
29590 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
295a0 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
295b0 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
295c0 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
295d0 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
295e0 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
295f0 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
29600 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
29610 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
29620 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
29630 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
29640 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
29650 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
29660 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
29670 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
29680 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
29690 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
296a0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
296b0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
296c0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
296d0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
296e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
296f0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
29700 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
29710 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
29720 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53  r_index()]..*/.S
29730 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
29740 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
29750 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
29760 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
29770 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
29780 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
29790 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
297a0 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
297b0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
297c0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
297d0 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
297e0 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
297f0 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
29800 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
29810 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
29820 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
29830 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
29840 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
29850 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
29860 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
29870 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
29880 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
29890 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
298a0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
298b0 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
298c0 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
298d0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
298e0 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
298f0 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
29900 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
29910 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
29920 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
29930 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
29940 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
29950 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
29960 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
29970 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
29980 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
29990 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
299a0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
299b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
299c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
299d0 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
299e0 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
299f0 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
29a00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
29a10 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
29a20 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
29a30 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
29a40 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
29a50 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
29a60 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
29a70 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
29a80 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
29a90 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
29aa0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
29ab0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29ac0 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69  nt]..** ^Use thi
29ad0 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
29ae0 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
29af0 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
29b00 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
29b10 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
29b20 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
29b30 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
29b40 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
29b50 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
29b60 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
29b70 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
29b80 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
29b90 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
29ba0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
29bb0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
29bc0 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73  tatement]. ^This
29bd0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
29be0 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
29bf0 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
29c00 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
29c10 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
29c20 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
29c30 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  DATE])..**.** Se
29c40 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
29c50 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
29c60 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
29c70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29c80 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
29c90 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
29ca0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
29cb0 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
29cc0 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
29cd0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
29ce0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
29cf0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
29d00 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
29d10 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
29d20 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
29d30 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
29d40 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
29d50 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
29d60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
29d70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
29d80 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
29d90 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
29da0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
29db0 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
29dc0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
29dd0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
29de0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
29df0 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
29e00 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
29e10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29e20 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
29e30 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
29e40 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
29e50 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
29e60 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
29e70 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
29e80 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
29e90 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
29ea0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
29eb0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
29ec0 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
29ed0 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
29ee0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29ef0 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
29f00 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
29f10 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
29f20 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
29f30 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
29f40 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
29f50 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
29f60 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
29f70 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
29f80 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
29f90 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
29fa0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
29fb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
29fc0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
29fd0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
29fe0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
29ff0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
2a000 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
2a010 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
2a020 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
2a030 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
2a040 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
2a050 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
2a060 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
2a070 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
2a080 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2a090 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2a0a0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
2a0b0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
2a0c0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2a0d0 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
2a0e0 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
2a0f0 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
2a100 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
2a110 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
2a120 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
2a130 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
2a140 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
2a150 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
2a160 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
2a170 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
2a180 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53  o the next..*/.S
2a190 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2a1a0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2a1b0 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
2a1c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
2a1d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2a1e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2a1f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
2a200 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a210 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
2a220 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
2a230 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
2a240 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Result.**.** ^Th
2a250 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
2a260 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
2a270 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
2a280 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
2a290 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
2a2a0 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
2a2b0 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
2a2c0 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
2a2d0 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
2a2e0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
2a2f0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
2a300 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
2a310 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
2a320 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
2a330 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
2a340 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
2a350 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
2a360 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
2a370 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
2a380 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
2a390 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
2a3a0 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
2a3b0 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
2a3c0 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
2a3d0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
2a3e0 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
2a3f0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2a400 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
2a410 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
2a420 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
2a430 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
2a440 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
2a450 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
2a460 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2a470 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
2a480 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
2a490 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
2a4a0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2a4b0 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
2a4c0 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
2a4d0 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
2a4e0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
2a4f0 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
2a500 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
2a510 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54  coding..**.** ^T
2a520 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
2a530 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
2a540 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
2a550 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
2a560 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
2a570 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
2a580 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
2a590 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e  ment to these in
2a5a0 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
2a5b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a5c0 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
2a5d0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
2a5e0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
2a5f0 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
2a600 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
2a610 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
2a620 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
2a630 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
2a640 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
2a650 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20   ^The left-most 
2a660 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e  column is column
2a670 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75   0 for these rou
2a680 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tines..**.** ^If
2a690 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2a6a0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
2a6b0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
2a6c0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
2a6d0 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
2a6e0 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
2a6f0 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
2a700 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2a710 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
2a720 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
2a730 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
2a740 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
2a750 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2a760 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
2a770 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65   ^Otherwise, the
2a780 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
2a790 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
2a7a0 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
2a7b0 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20  e,.** or column 
2a7c0 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
2a7d0 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
2a7e0 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
2a7f0 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20  ** ^As with all 
2a800 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
2a810 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e  s, those whose n
2a820 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31  ames end with "1
2a830 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
2a840 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
2a850 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65  ngs and the othe
2a860 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
2a870 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
2a880 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
2a890 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
2a8a0 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
2a8b0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
2a8c0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
2a8d0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
2a8e0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
2a8f0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a  essor symbol..**
2a900 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
2a910 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
2a920 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
2a930 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
2a940 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
2a950 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
2a960 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
2a970 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2a980 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2a990 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
2a9a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
2a9b0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
2a9c0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
2a9d0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
2a9e0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2a9f0 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
2aa00 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
2aa10 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
2aa20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2aa30 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
2aa40 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
2aa50 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2aa60 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2aa70 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53   undefined..*/.S
2aa80 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2aa90 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2aaa0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2aab0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2aac0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2aad0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2aae0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2aaf0 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
2ab00 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2ab10 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2ab20 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2ab30 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
2ab40 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2ab50 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2ab60 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2ab70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2ab80 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
2ab90 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2aba0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2abb0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2abc0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
2abd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2abe0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2abf0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2ac00 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2ac10 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2ac20 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2ac30 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
2ac40 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
2ac50 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2ac60 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
2ac70 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
2ac80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ac90 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
2aca0 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
2acb0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2acc0 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
2acd0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
2ace0 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
2acf0 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
2ad00 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
2ad10 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
2ad20 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2ad30 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
2ad40 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2ad50 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
2ad60 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
2ad70 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
2ad80 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2ad90 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
2ada0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2adb0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
2adc0 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
2add0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2ade0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2adf0 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
2ae00 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
2ae10 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
2ae20 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
2ae30 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
2ae40 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
2ae50 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
2ae60 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
2ae70 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
2ae80 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
2ae90 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
2aea0 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
2aeb0 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
2aec0 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
2aed0 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
2aee0 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
2aef0 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
2af00 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
2af10 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
2af20 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
2af30 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
2af40 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
2af50 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
2af60 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
2af70 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
2af80 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
2af90 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
2afa0 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
2afb0 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
2afc0 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
2afd0 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
2afe0 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
2aff0 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
2b000 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
2b010 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
2b020 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
2b030 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
2b040 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
2b050 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
2b060 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
2b070 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
2b080 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
2b090 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
2b0a0 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
2b0b0 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54  values..*/.SQLIT
2b0c0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2b0d0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2b0e0 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
2b0f0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2b100 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2b110 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2b120 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
2b130 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2b140 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b150 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
2b160 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
2b170 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
2b180 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b190 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
2b1a0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
2b1b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2b1c0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2b1d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2b1e0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
2b1f0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
2b200 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
2b210 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
2b220 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b230 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
2b240 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
2b250 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
2b260 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
2b270 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
2b280 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
2b290 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
2b2a0 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
2b2b0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
2b2c0 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
2b2d0 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
2b2e0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
2b2f0 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
2b300 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
2b310 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
2b320 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2b330 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2b340 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
2b350 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
2b360 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
2b370 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2b380 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2b390 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
2b3a0 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
2b3b0 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
2b3c0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
2b3d0 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
2b3e0 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
2b3f0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2b400 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
2b410 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
2b420 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
2b430 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2b440 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2b450 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
2b460 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
2b470 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
2b480 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
2b490 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2b4a0 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
2b4b0 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
2b4c0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
2b4d0 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
2b4e0 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
2b4f0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
2b500 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
2b510 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
2b520 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
2b530 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
2b540 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
2b550 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
2b560 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
2b570 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
2b580 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
2b590 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
2b5a0 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
2b5b0 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
2b5c0 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
2b5d0 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
2b5e0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
2b5f0 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
2b600 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
2b610 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
2b620 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
2b630 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
2b640 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
2b650 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
2b660 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
2b670 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
2b680 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
2b690 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
2b6a0 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
2b6b0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
2b6c0 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
2b6d0 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
2b6e0 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
2b6f0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
2b700 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
2b710 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
2b720 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
2b730 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
2b740 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
2b750 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
2b760 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
2b770 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
2b780 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
2b790 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2b7a0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
2b7b0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2b7c0 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
2b7d0 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
2b7e0 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
2b7f0 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
2b800 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
2b810 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
2b820 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
2b830 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
2b840 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
2b850 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
2b860 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
2b870 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
2b880 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
2b890 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
2b8a0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
2b8b0 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
2b8c0 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
2b8d0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
2b8e0 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
2b8f0 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
2b900 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
2b910 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
2b920 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
2b930 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
2b940 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
2b950 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
2b960 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
2b970 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
2b980 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
2b990 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
2b9a0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
2b9b0 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
2b9c0 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
2b9d0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
2b9e0 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
2b9f0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
2ba00 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
2ba10 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
2ba20 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
2ba30 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
2ba40 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
2ba50 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2ba60 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
2ba70 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2ba80 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
2ba90 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2baa0 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
2bab0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
2bac0 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
2bad0 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
2bae0 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
2baf0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2bb00 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2bb10 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
2bb20 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
2bb30 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
2bb40 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
2bb50 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
2bb60 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2bb70 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
2bb80 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
2bb90 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
2bba0 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
2bbb0 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
2bbc0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
2bbd0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
2bbe0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
2bbf0 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
2bc00 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
2bc10 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
2bc20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2bc30 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
2bc40 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
2bc50 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
2bc60 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
2bc70 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
2bc80 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
2bc90 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
2bca0 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
2bcb0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
2bcc0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
2bcd0 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65  as required afte
2bce0 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
2bcf0 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
2bd00 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  ng.** other than
2bd10 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65   [SQLITE_ROW] be
2bd20 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
2bd30 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
2bd40 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
2bd50 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
2bd60 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
2bd70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
2bd80 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
2bd90 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20  _reset()] would 
2bda0 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
2bdb0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
2bdc0 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  urn from.** sqli
2bdd0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
2bde0 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33   after version 3
2bdf0 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33  .6.23.1, sqlite3
2be00 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
2be10 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2be20 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
2be30 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
2be40 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
2be50 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
2be60 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
2be70 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
2be80 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
2be90 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
2bea0 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
2beb0 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
2bec0 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
2bed0 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
2bee0 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
2bef0 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
2bf00 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
2bf10 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
2bf20 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
2bf30 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
2bf40 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
2bf50 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
2bf60 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
2bf70 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
2bf80 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
2bf90 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2bfa0 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
2bfb0 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
2bfc0 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
2bfd0 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
2bfe0 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
2bff0 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
2c000 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
2c010 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
2c020 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
2c030 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
2c040 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
2c050 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
2c060 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2c070 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
2c080 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
2c090 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
2c0a0 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
2c0b0 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
2c0c0 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
2c0d0 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
2c0e0 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
2c0f0 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
2c100 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
2c110 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
2c120 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
2c130 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
2c140 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
2c150 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
2c160 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
2c170 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2c180 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c190 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
2c1a0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
2c1b0 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
2c1c0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
2c1d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2c1e0 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
2c1f0 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
2c200 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
2c210 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
2c220 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
2c230 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2c240 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
2c250 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
2c260 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
2c270 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2c280 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
2c290 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2c2a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c2b0 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
2c2c0 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
2c2d0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2c2e0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2c2f0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2c300 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2c310 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2c320 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77  e.** current row
2c330 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2c340 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
2c350 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
2c360 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74   ^If prepared st
2c370 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e  atement P does n
2c380 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20  ot have results 
2c390 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a  ready to return.
2c3a0 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f  ** (via calls to
2c3b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
2c3c0 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74  lumn_int | sqlit
2c3d0 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f  e3_column_*()] o
2c3e0 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29  f.** interfaces)
2c3f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61   then sqlite3_da
2c400 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75  ta_count(P) retu
2c410 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73  rns 0..** ^The s
2c420 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2c430 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73  t(P) routine als
2c440 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50  o returns 0 if P
2c450 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2c460 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  er..** ^The sqli
2c470 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2c480 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2c490 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69  s 0 if the previ
2c4a0 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ous call to.** [
2c4b0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2c4c0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2c4d0 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73  E_DONE].  ^The s
2c4e0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2c4f0 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74  t(P).** will ret
2c500 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20  urn non-zero if 
2c510 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2c520 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
2c530 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  P) returned.** [
2c540 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63  SQLITE_ROW], exc
2c550 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20  ept in the case 
2c560 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69  of the [PRAGMA i
2c570 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75  ncremental_vacuu
2c580 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61  m].** where it a
2c590 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65  lways returns ze
2c5a0 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74  ro since each st
2c5b0 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69  ep of that multi
2c5c0 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20  -step.** pragma 
2c5d0 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e  returns 0 column
2c5e0 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  s of data..**.**
2c5f0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2c600 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2c610 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ()].*/.SQLITE_AP
2c620 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  I int sqlite3_da
2c630 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
2c640 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2c650 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c660 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
2c670 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
2c680 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
2c690 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
2c6a0 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
2c6b0 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
2c6c0 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
2c6d0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2c6e0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
2c6f0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2c700 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
2c710 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2c720 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
2c730 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
2c740 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
2c750 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
2c760 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2c770 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
2c780 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
2c790 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
2c7a0 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
2c7b0 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
2c7c0 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
2c7d0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
2c7e0 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
2c7f0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
2c800 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
2c810 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
2c820 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
2c830 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
2c840 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
2c850 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
2c860 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
2c870 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
2c880 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c890 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
2c8a0 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
2c8b0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2c8c0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
2c8d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
2c8e0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
2c8f0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
2c900 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2c910 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
2c920 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
2c930 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
2c940 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
2c950 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
2c960 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
2c970 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
2c980 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
2c990 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2c9a0 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
2c9b0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
2c9c0 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22  the "result set"
2c9d0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2c9e0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2c9f0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2ca00 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
2ca10 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
2ca20 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
2ca30 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
2ca40 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63  ry.  ^In every c
2ca50 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
2ca60 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
2ca70 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
2ca80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ca90 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
2caa0 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
2cab0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
2cac0 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
2cad0 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
2cae0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2caf0 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
2cb00 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
2cb10 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
2cb20 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
2cb30 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
2cb40 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
2cb50 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
2cb60 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65  e returned. ^The
2cb70 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
2cb80 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2cb90 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
2cba0 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62   0..** ^The numb
2cbb0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2cbc0 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20   the result can 
2cbd0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
2cbe0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2cbf0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e  column_count()].
2cc00 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
2cc10 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
2cc20 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
2cc30 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
2cc40 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
2cc50 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
2cc60 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
2cc70 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
2cc80 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
2cc90 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
2cca0 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
2ccb0 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
2ccc0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
2ccd0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2cce0 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
2ccf0 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
2cd00 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
2cd10 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
2cd20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2cd30 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
2cd40 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
2cd50 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
2cd60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2cd70 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
2cd80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2cd90 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2cda0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
2cdb0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
2cdc0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2cdd0 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
2cde0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2cdf0 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
2ce00 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2ce10 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
2ce20 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
2ce30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2ce40 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2ce50 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
2ce60 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
2ce70 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
2ce80 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
2ce90 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
2cea0 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
2ceb0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2cec0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2ced0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2cee0 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
2cef0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
2cf00 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
2cf10 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
2cf20 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
2cf30 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
2cf40 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
2cf50 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
2cf60 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
2cf70 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
2cf80 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
2cf90 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
2cfa0 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
2cfb0 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
2cfc0 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
2cfd0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
2cfe0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2cff0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
2d000 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
2d010 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
2d020 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
2d030 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
2d040 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
2d050 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2d060 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
2d070 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2d080 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2d090 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
2d0a0 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
2d0b0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
2d0c0 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
2d0d0 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
2d0e0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
2d0f0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
2d100 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
2d110 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
2d120 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
2d130 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
2d140 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2d150 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
2d160 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2d170 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2d180 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
2d190 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
2d1a0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2d1b0 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
2d1c0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
2d1d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
2d1e0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
2d1f0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
2d200 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2d210 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2d220 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2d230 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2d240 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2d250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d260 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
2d270 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2d280 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2d290 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2d2a0 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
2d2b0 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
2d2c0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2d2d0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2d2e0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2d2f0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
2d300 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d310 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  es() returns zer
2d320 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  o..**.** ^If the
2d330 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
2d340 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  B or UTF-16 stri
2d350 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
2d360 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d370 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  16().** routine 
2d380 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2d390 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2d3a0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2d3b0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2d3c0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38  esult is a UTF-8
2d3d0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
2d3e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d3f0 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a  es16() converts.
2d400 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
2d410 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e   UTF-16 and then
2d420 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2d430 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
2d440 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2d450 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
2d460 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
2d470 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2d480 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2d490 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2d4a0 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2d4b0 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20  lue to a UTF-16 
2d4c0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2d4d0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
2d4e0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2d4f0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
2d500 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
2d510 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
2d520 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2d530 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
2d540 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  .**.** ^The valu
2d550 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
2d560 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d570 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20  ytes()] and .** 
2d580 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d590 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f  bytes16()] do no
2d5a0 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
2d5b0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61  ro terminators a
2d5c0 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
2d5d0 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f  the string.  ^Fo
2d5e0 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
2d5f0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2d600 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2d610 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
2d620 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
2d630 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65  n_bytes16()] are
2d640 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
2d650 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
2d660 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
2d670 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2d680 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69  ers..**.** ^Stri
2d690 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
2d6a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d6b0 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
2d6c0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2d6d0 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
2d6e0 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
2d6f0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
2d700 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  ated.  ^The retu
2d710 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
2d720 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d730 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
2d740 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73  o-length BLOB is
2d750 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2d760 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65  .**.** ^The obje
2d770 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
2d780 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2d790 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
2d7a0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2d7b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2d7c0 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65  ect.  An unprote
2d7d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2d7e0 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79  ue object.** may
2d7f0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
2d800 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  th [sqlite3_bind
2d810 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
2d820 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2d830 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
2d840 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
2d850 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2d860 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2d870 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2d880 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2d890 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
2d8a0 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
2d8b0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
2d8c0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
2d8d0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
2d8e0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2d8f0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
2d900 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2d910 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68  ytes()], then th
2d920 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2d930 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
2d940 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
2d950 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
2d960 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
2d970 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e   appropriate.  ^
2d980 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
2d990 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
2d9a0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
2d9b0 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
2d9c0 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
2d9d0 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
2d9e0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2d9f0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
2da00 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
2da10 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
2da20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2da30 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
2da40 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
2da50 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
2da60 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
2da70 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
2da80 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
2da90 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
2daa0 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
2dab0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
2dac0 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
2dad0 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
2dae0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
2daf0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
2db00 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
2db10 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
2db20 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2db30 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2db40 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
2db50 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2db60 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
2db70 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2db80 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
2db90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2dba0 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
2dbb0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2dbc0 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
2dbd0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2dbe0 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
2dbf0 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
2dc00 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
2dc10 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
2dc20 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2dc30 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2dc40 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
2dc50 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
2dc60 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2dc70 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
2dc80 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
2dc90 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
2dca0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2dcb0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2dcc0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
2dcd0 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74  rom float to int
2dce0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
2dcf0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
2dd00 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
2dd10 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
2dd20 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
2dd30 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2dd40 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2dd50 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41  td> Same as FLOA
2dd60 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  T->TEXT.** <tr><
2dd70 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2dd80 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2dd90 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   Use atoi().** <
2dda0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2ddb0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2ddc0 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a  <td> Use atof().
2ddd0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
2dde0 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
2ddf0 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
2de00 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
2de10 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
2de20 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
2de30 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
2de40 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   use atoi().** <
2de50 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2de60 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2de70 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
2de80 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
2de90 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
2dea0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
2deb0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
2dec0 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
2ded0 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
2dee0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
2def0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
2df00 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f  ** The table abo
2df10 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e  ve makes referen
2df20 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43  ce to standard C
2df30 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f   library functio
2df40 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64  ns atoi().** and
2df50 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65   atof().  SQLite
2df60 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79   does not really
2df70 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74   use these funct
2df80 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74  ions.  It has it
2df90 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c  s.** own equival
2dfa0 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
2dfb0 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
2dfc0 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
2dfd0 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
2dfe0 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
2dff0 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
2e000 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
2e010 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
2e020 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
2e030 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2e040 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
2e050 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
2e060 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
2e070 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
2e080 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2e090 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
2e0a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2e0b0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
2e0c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e0d0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
2e0e0 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
2e0f0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
2e100 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
2e110 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
2e120 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
2e130 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
2e140 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2e150 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2e160 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
2e170 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2e180 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
2e190 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2e1a0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
2e1b0 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
2e1c0 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
2e1d0 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
2e1e0 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
2e1f0 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
2e200 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
2e210 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
2e220 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
2e230 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2e240 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
2e250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2e260 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
2e270 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2e280 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2e290 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2e2a0 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
2e2b0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2e2c0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
2e2d0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2e2e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2e2f0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2e300 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2e310 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
2e320 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
2e330 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
2e340 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
2e350 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2e360 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
2e370 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
2e380 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
2e390 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
2e3a0 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
2e3b0 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
2e3c0 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
2e3d0 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
2e3e0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2e3f0 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
2e400 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
2e410 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69  er references wi
2e420 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
2e430 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
2e440 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
2e450 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
2e460 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
2e470 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
2e480 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
2e490 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
2e4a0 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
2e4b0 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
2e4c0 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
2e4d0 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
2e4e0 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
2e4f0 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
2e500 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
2e510 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
2e520 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
2e530 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
2e540 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2e550 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2e560 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
2e570 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2e580 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2e590 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2e5a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2e5b0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2e5c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e5d0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
2e5e0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2e5f0 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
2e600 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2e610 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
2e620 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2e630 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
2e640 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
2e650 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
2e660 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
2e670 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2e680 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
2e690 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
2e6a0 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
2e6b0 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
2e6c0 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
2e6d0 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
2e6e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e6f0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
2e700 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e710 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
2e720 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
2e730 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
2e740 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
2e750 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2e760 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2e770 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
2e780 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
2e790 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e7a0 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
2e7b0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
2e7c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e7d0 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
2e7e0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2e7f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2e800 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
2e810 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
2e820 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
2e830 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2e840 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
2e850 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
2e860 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
2e870 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
2e880 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2e890 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2e8a0 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
2e8b0 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
2e8c0 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
2e8d0 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
2e8e0 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
2e8f0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
2e900 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
2e910 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
2e920 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
2e930 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
2e940 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
2e950 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e960 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
2e970 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
2e980 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
2e990 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2e9a0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
2e9b0 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
2e9c0 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
2e9d0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2e9e0 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
2e9f0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
2ea00 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
2ea10 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
2ea20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
2ea30 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
2ea40 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
2ea50 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2ea60 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
2ea70 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2ea80 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
2ea90 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
2eaa0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
2eab0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2eac0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2ead0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
2eae0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2eaf0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2eb00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2eb10 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
2eb20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2eb30 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
2eb40 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2eb50 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
2eb60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2eb70 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64  l);.SQLITE_API d
2eb80 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
2eb90 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
2eba0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2ebb0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2ebc0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2ebd0 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
2ebe0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2ebf0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
2ec00 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
2ec10 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
2ec20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ec30 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2ec40 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67  _API const unsig
2ec50 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
2ec60 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
2ec70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ec80 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2ec90 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2eca0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2ecb0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2ecc0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
2ecd0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2ece0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2ecf0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2ed00 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2ed10 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76  TE_API sqlite3_v
2ed20 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
2ed30 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
2ed40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2ed50 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
2ed60 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
2ed70 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2ed80 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
2ed90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
2eda0 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
2edb0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
2edc0 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
2edd0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2ede0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2edf0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
2ee00 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2ee10 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65  encountered no e
2ee20 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74  rrors.** or if t
2ee30 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2ee40 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75  never been evalu
2ee50 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ated, then sqlit
2ee60 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65  e3_finalize() re
2ee70 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f  turns.** SQLITE_
2ee80 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73  OK.  ^If the mos
2ee90 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
2eea0 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74  ion of statement
2eeb0 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a   S failed, then.
2eec0 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ** sqlite3_final
2eed0 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74  ize(S) returns t
2eee0 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  he appropriate [
2eef0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a  error code] or.*
2ef00 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  * [extended erro
2ef10 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
2ef20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
2ef30 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20  lize(S) routine 
2ef40 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
2ef50 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
2ef60 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79  g.** the life cy
2ef70 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64  cle of [prepared
2ef80 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a   statement] S:.*
2ef90 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65  * before stateme
2efa0 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61  nt S is ever eva
2efb0 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a  luated, after.**
2efc0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c   one or more cal
2efd0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
2efe0 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65  eset()], or afte
2eff0 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f  r any call.** to
2f000 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2f010 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  ] regardless of 
2f020 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
2f030 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
2f040 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
2f050 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ecution..**.** ^
2f060 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  Invoking sqlite3
2f070 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61  _finalize() on a
2f080 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2f090 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
2f0a0 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  p..**.** The app
2f0b0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69  lication must fi
2f0c0 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72  nalize every [pr
2f0d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f0e0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76  ] in order to av
2f0f0 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20  oid.** resource 
2f100 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20  leaks.  It is a 
2f110 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66  grievous error f
2f120 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
2f130 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65  on to try to use
2f140 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73  .** a prepared s
2f150 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
2f160 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
2f170 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f  ized.  Any use o
2f180 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  f a prepared.** 
2f190 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
2f1a0 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
2f1b0 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74  lized can result
2f1c0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
2f1d0 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  d.** undesirable
2f1e0 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61   behavior such a
2f1f0 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20  s segfaults and 
2f200 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e  heap corruption.
2f210 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2f220 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
2f230 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
2f240 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2f250 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2f260 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2f270 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
2f280 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2f290 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
2f2a0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
2f2b0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
2f2c0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
2f2d0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
2f2e0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
2f2f0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
2f300 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
2f310 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
2f320 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
2f330 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
2f340 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
2f350 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2f360 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2f370 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
2f380 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
2f390 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
2f3a0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
2f3b0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
2f3c0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
2f3d0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
2f3e0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
2f3f0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
2f400 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f410 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
2f420 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
2f430 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
2f440 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
2f450 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2f460 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2f470 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
2f480 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f490 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
2f4a0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
2f4b0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
2f4c0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
2f4d0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
2f4e0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
2f4f0 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
2f500 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
2f510 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
2f520 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
2f530 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2f540 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2f550 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2f560 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2f570 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2f580 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
2f590 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
2f5a0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2f5b0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
2f5c0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2f5d0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2f5e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2f5f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
2f600 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2f610 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
2f620 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
2f630 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
2f640 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
2f650 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
2f660 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2f670 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
2f680 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2f690 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2f6a0 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
2f6b0 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
2f6c0 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
2f6d0 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
2f6e0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
2f6f0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
2f700 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2f710 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
2f720 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
2f730 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2f740 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
2f750 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
2f760 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
2f770 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
2f780 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
2f790 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
2f7a0 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
2f7b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
2f7c0 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
2f7d0 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
2f7e0 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
2f7f0 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
2f800 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
2f810 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
2f820 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65  fferences betwee
2f830 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69  n.** these routi
2f840 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74  nes are the text
2f850 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74   encoding expect
2f860 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65  ed for.** the se
2f870 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
2f880 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2f890 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63  function being c
2f8a0 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74  reated).** and t
2f8b0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61  he presence or a
2f8c0 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74  bsence of a dest
2f8d0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
2f8e0 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  for.** the appli
2f8f0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
2f900 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2f910 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2f920 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
2f930 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
2f940 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
2f950 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
2f960 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
2f970 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
2f980 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
2f990 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
2f9a0 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
2f9b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2f9c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
2f9d0 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
2f9e0 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
2f9f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
2fa00 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rately..**.** ^T
2fa10 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2fa20 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
2fa30 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
2fa40 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
2fa50 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
2fa60 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
2fa70 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
2fa80 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
2fa90 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a  tes in a UTF-8.*
2faa0 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  * representation
2fab0 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
2fac0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
2fad0 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  or.  ^Note that 
2fae0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67  the name.** leng
2faf0 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55  th limit is in U
2fb00 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20  TF-8 bytes, not 
2fb10 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55  characters nor U
2fb20 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a  TF-16 bytes.  .*
2fb30 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74  * ^Any attempt t
2fb40 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
2fb50 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
2fb60 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
2fb70 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
2fb80 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72  _MISUSE] being r
2fb90 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2fba0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
2fbb0 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
2fbc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
2fbd0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
2fbe0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2fbf0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
2fc00 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
2fc10 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
2fc20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
2fc30 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2fc40 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
2fc50 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
2fc60 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
2fc70 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
2fc80 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
2fc90 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
2fca0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2fcb0 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
2fcc0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
2fcd0 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
2fce0 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
2fcf0 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
2fd00 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
2fd10 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2fd20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
2fd30 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
2fd40 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
2fd50 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
2fd60 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
2fd70 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
2fd80 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
2fd90 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
2fda0 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63    Every SQL func
2fdb0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2fdc0 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65  ion must be able
2fdd0 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68   to work.** with
2fde0 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65   UTF-8, UTF-16le
2fdf0 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20  , or UTF-16be.  
2fe00 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65  But some impleme
2fe10 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a  ntations may be.
2fe20 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e  ** more efficien
2fe30 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64  t with one encod
2fe40 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72  ing than another
2fe50 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  .  ^An applicati
2fe60 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65  on may.** invoke
2fe70 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2fe80 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
2fe90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2fea0 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
2feb0 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
2fec0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2fed0 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
2fee0 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
2fef0 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68  eTextRep..** ^Wh
2ff00 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
2ff10 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2ff20 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2ff30 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
2ff40 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
2ff50 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
2ff60 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
2ff70 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
2ff80 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
2ff90 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e  * If there is on
2ffa0 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c  ly a single impl
2ffb0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68  ementation which
2ffc0 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77   does not care w
2ffd0 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f  hat text.** enco
2ffe0 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ding is used, th
2fff0 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  en the fourth ar
30000 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
30010 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a   [SQLITE_ANY]..*
30020 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
30030 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
30040 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
30050 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
30060 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
30070 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
30080 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
30090 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
300a0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
300b0 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
300c0 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65  ^The sixth, seve
300d0 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70  nth and eighth p
300e0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
300f0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
30100 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
30110 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
30120 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
30130 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
30140 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
30150 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
30160 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
30170 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
30180 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
30190 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
301a0 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
301b0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
301c0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
301d0 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
301e0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
301f0 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
30200 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
30210 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
30220 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
30230 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
30240 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
30250 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
30260 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
30270 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
30280 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
30290 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
302a0 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ass NULL pointer
302b0 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  s for all three 
302c0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
302d0 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  backs..**.** ^(I
302e0 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61  f the ninth para
302f0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
30300 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30310 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  _v2() is not NUL
30320 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  L,.** then it is
30330 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
30340 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
30350 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a  data pointer. .*
30360 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  * The destructor
30370 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
30380 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
30390 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72   deleted, either
303a0 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65   by being.** ove
303b0 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20  rloaded or when 
303c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
303d0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29  nection closes.)
303e0 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75  ^.** ^The destru
303f0 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76  ctor is also inv
30400 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
30410 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
30420 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
30430 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57  2() fails..** ^W
30440 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
30450 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  or callback of t
30460 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74  he tenth paramet
30470 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  er is invoked, i
30480 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61  t.** is passed a
30490 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
304a0 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79   which is a copy
304b0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
304c0 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69  ion data .** poi
304d0 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
304e0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
304f0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
30500 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
30510 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ()..**.** ^It is
30520 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
30530 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
30540 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
30550 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
30560 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
30570 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
30580 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
30590 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
305a0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
305b0 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
305c0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
305d0 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
305e0 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
305f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
30600 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
30610 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
30620 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
30630 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
30640 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  sed.  ^A functio
30650 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
30660 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
30670 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
30680 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
30690 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
306a0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
306b0 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
306c0 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
306d0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68    ^A function wh
306e0 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
306f0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
30700 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
30710 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
30720 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
30730 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
30740 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
30750 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
30760 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66  erent.  .** ^A f
30770 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
30780 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
30790 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
307a0 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
307b0 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
307c0 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
307d0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
307e0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
307f0 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
30800 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
30810 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69  TF16..**.** ^Bui
30820 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
30830 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
30840 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
30850 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
30860 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  ctions..**.** ^A
30870 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
30880 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
30890 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
308a0 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
308b0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
308c0 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
308d0 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
308e0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
308f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
30900 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
30910 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
30920 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
30930 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
30940 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
30950 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
30960 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
30970 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
30980 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
30990 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
309a0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
309b0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
309c0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
309d0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
309e0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
309f0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
30a00 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
30a10 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
30a20 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
30a30 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
30a40 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
30a50 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30a60 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
30a70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
30a80 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
30a90 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
30aa0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
30ab0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
30ac0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
30ad0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
30ae0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
30af0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
30b00 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
30b10 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
30b20 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
30b30 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
30b40 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
30b50 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
30b60 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
30b70 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  text*).);.SQLITE
30b80 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
30b90 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30ba0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
30bb0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
30bc0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
30bd0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
30be0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
30bf0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
30c00 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
30c10 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
30c20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
30c30 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
30c40 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
30c50 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
30c60 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
30c70 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
30c80 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
30c90 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
30ca0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
30cb0 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
30cc0 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
30cd0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
30ce0 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
30cf0 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
30d00 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
30d10 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
30d20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
30d30 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
30d40 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
30d50 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
30d60 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
30d70 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
30d80 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
30d90 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
30da0 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
30db0 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
30dc0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
30dd0 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
30de0 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
30df0 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
30e00 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
30e10 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
30e20 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
30e30 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
30e40 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
30e50 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
30e60 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
30e70 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
30e80 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
30e90 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
30ea0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
30eb0 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
30ec0 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
30ed0 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
30ee0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
30ef0 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
30f00 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
30f10 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
30f20 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
30f30 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
30f40 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
30f50 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
30f60 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
30f70 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
30f80 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
30f90 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
30fa0 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
30fb0 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
30fc0 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
30fd0 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
30fe0 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
30ff0 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
31000 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
31010 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
31020 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
31030 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
31040 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
31050 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
31060 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
31070 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
31080 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
31090 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
310a0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
310b0 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
310c0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
310d0 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
310e0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  stmt*);.SQLITE_A
310f0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
31100 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
31110 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
31120 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
31130 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
31140 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
31150 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
31160 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
31170 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
31180 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
31190 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
311a0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
311b0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20  e3_int64,int),. 
311c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
311d0 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74       void*,sqlit
311e0 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
311f0 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
31200 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
31210 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
31220 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a  ter Values.**.**
31230 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
31240 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
31250 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
31260 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
31270 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
31280 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
31290 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
312a0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
312b0 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
312c0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
312d0 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
312e0 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
312f0 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
31300 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
31310 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
31320 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
31330 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31340 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
31350 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31360 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
31370 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
31380 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
31390 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
313a0 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
313b0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
313c0 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
313d0 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
313e0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
313f0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
31400 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
31410 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
31420 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
31430 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
31440 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
31450 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
31460 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
31470 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
31480 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
31490 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
314a0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
314b0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
314c0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
314d0 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
314e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
314f0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
31500 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
31510 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
31520 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
31530 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31540 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
31550 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
31560 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
31570 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
31580 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
31590 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
315a0 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  g [column access
315b0 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65   functions].** e
315c0 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73  xcept that  thes
315d0 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20  e routines take 
315e0 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63  a single [protec
315f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
31600 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69  e] object.** poi
31610 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
31620 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  a [sqlite3_stmt*
31630 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
31640 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
31650 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  number..**.** ^T
31660 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
31670 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66  _text16() interf
31680 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55  ace extracts a U
31690 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  TF-16 string.** 
316a0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
316b0 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te-order of the 
316c0 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e  host machine.  ^
316d0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
316e0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
316f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
31700 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
31710 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
31720 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
31730 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
31740 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
31750 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
31760 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
31770 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
31780 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
31790 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
317a0 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
317b0 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
317c0 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
317d0 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
317e0 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
317f0 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
31800 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
31810 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
31820 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
31830 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
31840 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
31850 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
31860 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
31870 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
31880 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
31890 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
318a0 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
318b0 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
318c0 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
318d0 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
318e0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
318f0 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
31900 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
31910 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
31920 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
31930 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  d.)^.**.** Pleas
31940 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
31950 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
31960 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
31970 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64  pointer returned
31980 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
31990 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
319a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
319b0 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
319c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
319d0 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
319e0 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
319f0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
31a00 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
31a10 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
31a20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
31a30 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
31a40 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
31a50 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
31a60 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
31a70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
31a80 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
31a90 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
31aa0 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
31ab0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
31ac0 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
31ad0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
31ae0 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
31af0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
31b00 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31b10 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
31b20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
31b30 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
31b40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
31b50 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
31b60 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
31b70 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
31b80 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
31b90 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
31ba0 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  API double sqlit
31bb0 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
31bc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31bd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
31be0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
31bf0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
31c00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
31c10 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
31c20 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
31c30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31c40 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
31c50 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
31c60 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
31c70 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
31c80 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
31c90 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
31ca0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
31cb0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31cc0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
31cd0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31ce0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
31cf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31d00 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
31d10 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
31d20 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
31d30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31d40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
31d50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
31d60 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
31d70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
31d80 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
31d90 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
31da0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
31db0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
31dc0 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
31dd0 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
31de0 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74  .**.** Implement
31df0 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67  ations of aggreg
31e00 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
31e10 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f  s use this.** ro
31e20 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
31e30 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f  e memory for sto
31e40 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
31e50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
31e60 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
31e70 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
31e80 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
31e90 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a  ne is called .**
31ea0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
31eb0 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  r aggregate func
31ec0 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  tion, SQLite.** 
31ed0 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d  allocates N of m
31ee0 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
31ef0 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  t that memory, a
31f00 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
31f10 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e  nter.** to the n
31f20 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73  ew memory. ^On s
31f30 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
31f40 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
31f50 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
31f60 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
31f70 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
31f80 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
31f90 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61  tance,.** the sa
31fa0 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
31fb0 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f  urned.  Sqlite3_
31fc0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31fd0 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a  t() is normally.
31fe0 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66  ** called once f
31ff0 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  or each invocati
32000 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20  on of the xStep 
32010 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65  callback and the
32020 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69  n one.** last ti
32030 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e  me when the xFin
32040 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  al callback is i
32050 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20  nvoked.  ^(When 
32060 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a  no rows match.**
32070 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75   an aggregate qu
32080 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29  ery, the xStep()
32090 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
320a0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
320b0 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
320c0 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63  ation is never c
320d0 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c  alled and xFinal
320e0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61  () is called exa
320f0 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e  ctly once..** In
32100 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71   those cases, sq
32110 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
32120 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20  context() might 
32130 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  be called for th
32140 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20  e.** first time 
32150 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e  from within xFin
32160 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  al().)^.**.** ^T
32170 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
32180 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
32190 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
321a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
321b0 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20   .** when first 
321c0 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c  called if N is l
321d0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
321e0 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20  l to zero or if 
321f0 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  a memory.** allo
32200 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
32210 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
32220 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
32230 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
32240 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
32250 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
32260 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
32270 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
32280 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
32290 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
322a0 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
322b0 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
322c0 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
322d0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
322e0 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
322f0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
32300 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
32310 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
32320 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
32330 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
32340 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46  ^  Within the xF
32350 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69  inal callback, i
32360 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74  t is customary t
32370 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20  o set.** N=0 in 
32380 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
32390 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
323a0 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20  xt(C,N) so that 
323b0 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73  no .** pointless
323c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
323d0 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a  ons occur..**.**
323e0 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74   ^SQLite automat
323f0 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
32400 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
32410 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
32420 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
32430 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67  xt() when the ag
32440 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f  gregate query co
32450 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
32460 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
32470 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70  er must be a cop
32480 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  y of the.** [sql
32490 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
324a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
324b0 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
324c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
324d0 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70  .** to the xStep
324e0 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
324f0 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
32500 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
32510 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
32520 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
32530 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
32540 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
32550 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
32560 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
32570 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
32580 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
32590 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
325a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
325b0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
325c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
325d0 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
325e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
325f0 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
32600 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
32610 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
32620 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
32630 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
32640 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
32650 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
32660 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
32670 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
32680 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
32690 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
326a0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
326b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
326c0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
326d0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
326e0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
326f0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
32700 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
32710 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
32720 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
32730 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
32740 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
32750 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
32760 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32770 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
32780 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
32790 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
327a0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
327b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
327c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
327d0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
327e0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
327f0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
32800 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
32810 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
32820 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
32830 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
32840 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
32850 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32860 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
32870 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
32880 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
32890 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
328a0 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
328b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
328c0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
328d0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
328e0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
328f0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
32900 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
32910 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
32920 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
32930 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
32940 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
32950 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32960 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
32970 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
32980 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
32990 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 28  may be used by (
329a0 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53  non-aggregate) S
329b0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
329c0 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
329d0 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  adata with argum
329e0 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
329f0 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
32a00 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
32a10 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
32a20 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
32a30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
32a40 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
32a50 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
32a60 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
32a70 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
32a80 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70  etadata may be p
32a90 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78  reserved.  An ex
32aa0 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72  ample.** of wher
32ab0 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 20  e this might be 
32ac0 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72  useful is in a r
32ad0 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
32ae0 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75  n matching.** fu
32af0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
32b00 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
32b10 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
32b20 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74  ession can be st
32b30 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64  ored as.** metad
32b40 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
32b50 69 74 68 20 74 68 65 20 70 61 74 74 65 72 6e 20  ith the pattern 
32b60 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65  string.  .** The
32b70 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  n as long as the
32b80 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20   pattern string 
32b90 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65  remains the same
32ba0 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65  ,.** the compile
32bb0 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
32bc0 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
32bd0 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
32be0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
32bf0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
32c00 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
32c10 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
32c20 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
32c30 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
32c40 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
32c50 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
32c60 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
32c70 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
32c80 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
32c90 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
32ca0 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
32cb0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
32cc0 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65  unction. ^If the
32cd0 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74  re is no metadat
32ce0 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
32cf0 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f  with the functio
32d00 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73  n argument, this
32d10 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
32d20 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
32d30 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55  .** returns a NU
32d40 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
32d50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
32d60 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
32d70 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  ,X) interface sa
32d80 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 61 74  ves P as metadat
32d90 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a  a for the N-th.*
32da0 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  * argument of th
32db0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
32dc0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
32dd0 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20   ^Subsequent.** 
32de0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
32df0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _get_auxdata(C,N
32e00 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20  ) return P from 
32e10 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
32e20 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
32e30 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
32e40 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61  call if the meta
32e50 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61  data is still va
32e60 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69  lid or.** NULL i
32e70 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 68  f the metadata h
32e80 61 73 20 62 65 65 6e 20 64 69 73 63 61 72 64 65  as been discarde
32e90 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63  d..** ^After eac
32ea0 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
32eb0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
32ec0 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20 69  N,P,X) where X i
32ed0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53  s not NULL,.** S
32ee0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
32ef0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
32f00 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68   function X with
32f10 20 70 61 72 61 6d 65 74 65 72 20 50 20 65 78 61   parameter P exa
32f20 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68  ctly.** once, wh
32f30 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  en the metadata 
32f40 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  is discarded..**
32f50 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
32f60 74 6f 20 64 69 73 63 61 72 64 20 74 68 65 20 6d  to discard the m
32f70 65 74 61 64 61 74 61 20 61 74 20 61 6e 79 20 74  etadata at any t
32f80 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20  ime, including: 
32f90 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  <ul>.** <li> whe
32fa0 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
32fb0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
32fc0 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20  ameter changes, 
32fd0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  or.** <li> when 
32fe0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32ff0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
33000 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
33010 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  led for the.**  
33020 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e      SQL statemen
33030 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68  t, or.** <li> wh
33040 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  en sqlite3_set_a
33050 75 78 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f  uxdata() is invo
33060 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65  ked again on the
33070 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c   same parameter,
33080 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69   or.** <li> duri
33090 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ng the original 
330a0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
330b0 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20  ata() call when 
330c0 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20  a memory .**    
330d0 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72    allocation err
330e0 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e  or occurs. </ul>
330f0 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  )^.**.** Note th
33100 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e  e last bullet in
33110 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68   particular.  Th
33120 65 20 64 65 73 74 72 75 63 74 6f 72 20 58 20 69  e destructor X i
33130 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  n .** sqlite3_se
33140 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
33150 58 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  X) might be call
33160 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ed immediately, 
33170 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71  before the.** sq
33180 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33190 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 76  a() interface ev
331a0 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e  en returns.  Hen
331b0 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ce sqlite3_set_a
331c0 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75  uxdata().** shou
331d0 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61  ld be called nea
331e0 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  r the end of the
331f0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
33200 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65  entation and the
33210 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  .** function imp
33220 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
33230 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20  ld not make any 
33240 75 73 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a  use of P after.*
33250 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
33260 78 64 61 74 61 28 29 20 68 61 73 20 62 65 65 6e  xdata() has been
33270 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   called..**.** ^
33280 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
33290 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
332a0 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
332b0 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
332c0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
332d0 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 63  eters that are c
332e0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73  ompile-time cons
332f0 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67  tants, including
33300 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75   literal.** valu
33310 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65  es and [paramete
33320 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69  rs] and expressi
33330 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f  ons composed fro
33340 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a  m the same.)^.**
33350 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
33360 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
33370 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
33380 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
33390 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
333a0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
333b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
333c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
333d0 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
333e0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29  context*, int N)
333f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
33400 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
33410 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
33420 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
33430 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
33440 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
33450 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
33460 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
33470 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
33480 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54  Behavior.**.** T
33490 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
334a0 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
334b0 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
334c0 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
334d0 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
334e0 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
334f0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
33500 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
33510 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63   ^If the destruc
33520 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
33530 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
33540 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
33550 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
33560 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
33570 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
33580 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
33590 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
335a0 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54  e destroyed.  ^T
335b0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
335c0 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
335d0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
335e0 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
335f0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
33600 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
33610 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
33620 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
33630 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
33640 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
33650 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
33660 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
33670 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
33680 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
33690 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
336a0 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
336b0 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  lers..*/.typedef
336c0 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
336d0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
336e0 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
336f0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
33700 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
33710 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
33720 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33730 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
33740 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
33750 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
33760 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
33770 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
33780 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
33790 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
337a0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62  tines are used b
337b0 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  y the xFunc or x
337c0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  Final callbacks 
337d0 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  that.** implemen
337e0 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
337f0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20  and aggregates. 
33800 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   See.** [sqlite3
33810 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33820 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
33830 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33840 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64  16()].** for add
33850 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
33860 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion..**.** These
33870 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20   functions work 
33880 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74  very much like t
33890 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69  he [parameter bi
338a0 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66  nding] family of
338b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  .** functions us
338c0 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ed to bind value
338d0 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
338e0 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
338f0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
33900 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51  Refer to the [SQ
33910 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63  L parameter] doc
33920 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
33930 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
33940 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
33950 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33960 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
33970 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
33980 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
33990 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
339a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
339b0 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
339c0 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
339d0 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
339e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
339f0 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
33a00 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
33a10 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
33a20 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
33a30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33a40 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
33a50 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
33a60 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
33a70 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
33a80 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
33a90 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
33aa0 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
33ab0 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
33ac0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
33ad0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
33ae0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
33af0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
33b00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33b10 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
33b20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
33b30 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
33b40 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
33b50 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
33b60 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
33b70 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
33b80 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
33b90 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
33ba0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33bb0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33bc0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
33bd0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
33be0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
33bf0 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
33c00 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
33c10 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
33c20 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ption..** ^SQLit
33c30 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e  e uses the strin
33c40 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
33c50 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d  the.** 2nd param
33c60 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
33c70 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
33c80 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
33c90 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73  _error16().** as
33ca0 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
33cb0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20  error message.  
33cc0 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65  ^SQLite interpre
33cd0 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
33ce0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
33cf0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
33d00 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
33d10 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  F-8. ^SQLite.** 
33d20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
33d30 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
33d40 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
33d50 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
33d60 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
33d70 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20  order.  ^If the 
33d80 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
33d90 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
33da0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
33db0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33dc0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61  rror16() is nega
33dd0 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
33de0 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72   takes as the er
33df0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61  ror.** message a
33e00 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75  ll text up throu
33e10 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
33e20 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
33e30 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
33e40 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
33e50 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
33e60 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
33e70 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
33e80 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
33e90 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
33ea0 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
33eb0 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
33ec0 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
33ed0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
33ee0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
33ef0 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ge..** ^The sqli
33f00 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33f10 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
33f20 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
33f30 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
33f40 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20   a private copy 
33f50 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
33f60 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
33f70 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
33f80 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
33f90 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
33fa0 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
33fb0 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
33fc0 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
33fd0 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
33fe0 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  m..** ^The sqlit
33ff0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
34000 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  code() function 
34010 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f  changes the erro
34020 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e  r code.** return
34030 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20  ed by SQLite as 
34040 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65  a result of an e
34050 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69  rror in a functi
34060 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74  on.  ^By default
34070 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
34080 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
34090 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75  ROR.  ^A subsequ
340a0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
340b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
340c0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
340d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
340e0 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72  ) resets the err
340f0 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54  or code to SQLIT
34100 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e  E_ERROR..**.** ^
34110 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34120 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
34130 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
34140 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
34150 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69  ow an.** error i
34160 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
34170 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
34180 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
34190 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
341a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
341b0 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
341c0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
341d0 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
341e0 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69  ow an.** error i
341f0 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
34200 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
34210 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  on failed..**.**
34220 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
34230 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72  sult_int() inter
34240 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
34250 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
34260 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34270 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
34280 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62  n to be the 32-b
34290 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
342a0 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
342b0 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
342c0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ment..** ^The sq
342d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
342e0 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
342f0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
34300 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
34310 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34320 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
34330 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67  e the 64-bit sig
34340 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
34350 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
34360 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
34370 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34380 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29  e3_result_null()
34390 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
343a0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
343b0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
343c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
343d0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55  unction to be NU
343e0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
343f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34400 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  xt(), sqlite3_re
34410 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a  sult_text16(),.*
34420 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
34430 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64  _text16le(), and
34440 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34450 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72  text16be() inter
34460 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65  faces.** set the
34470 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
34480 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34490 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
344a0 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78  n to be.** a tex
344b0 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  t string which i
344c0 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73  s represented as
344d0 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e   UTF-8, UTF-16 n
344e0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
344f0 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
34500 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le endian, or UT
34510 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c  F-16 big endian,
34520 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
34530 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20  * ^SQLite takes 
34540 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
34550 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
34560 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
34570 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
34580 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
34590 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
345a0 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  faces..** ^If th
345b0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
345c0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
345d0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
345e0 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67  rfaces.** is neg
345f0 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69  ative, then SQLi
34600 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20  te takes result 
34610 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e  text from the 2n
34620 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
34630 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
34640 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
34650 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
34660 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
34670 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34680 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
34690 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
346a0 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
346b0 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
346c0 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
346d0 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
346e0 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
346f0 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
34700 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
34710 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
34720 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
34730 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72    If the 3rd par
34740 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65  ameter is non-ne
34750 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a  gative, then it.
34760 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  ** must be the b
34770 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20  yte offset into 
34780 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
34790 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
347a0 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70  tor would.** app
347b0 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e  ear if the strin
347c0 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d  g where NUL term
347d0 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
347e0 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
347f0 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73  ccur.** in the s
34800 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20  tring at a byte 
34810 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c  offset that is l
34820 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c  ess than the val
34830 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a  ue of the 3rd.**
34840 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
34850 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
34860 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61  tring will conta
34870 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
34880 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75   and the.** resu
34890 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
348a0 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73  s operating on s
348b0 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65  trings with embe
348c0 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
348d0 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  efined..** ^If t
348e0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
348f0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
34900 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
34910 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
34920 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
34930 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  b is a non-NULL 
34940 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
34950 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a  Lite calls that.
34960 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74  ** function as t
34970 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e  he destructor on
34980 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
34990 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74  B result when it
349a0 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64   has.** finished
349b0 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
349c0 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
349d0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
349e0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
349f0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
34a00 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c  ces or to.** sql
34a10 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
34a20 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
34a30 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
34a40 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c  STATIC, then SQL
34a50 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74  ite.** assumes t
34a60 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20  hat the text or 
34a70 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69  BLOB result is i
34a80 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65  n constant space
34a90 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a   and does not.**
34aa0 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e   copy the conten
34ab0 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  t of the paramet
34ac0 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65  er nor call a de
34ad0 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
34ae0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20  content.** when 
34af0 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
34b00 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
34b10 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
34b20 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
34b30 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34b40 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
34b50 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
34b60 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
34b70 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
34b80 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e  tant SQLITE_TRAN
34b90 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51  SIENT.** then SQ
34ba0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
34bb0 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  y of the result 
34bc0 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69  into space obtai
34bd0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d  ned from.** from
34be0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
34bf0 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65  ()] before it re
34c00 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
34c10 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34c20 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
34c30 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
34c40 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
34c50 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34c60 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
34c70 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75  a copy the.** [u
34c80 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
34c90 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
34ca0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
34cb0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
34cc0 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
34cd0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
34ce0 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73   interface makes
34cf0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
34d00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
34d10 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73  * so that the [s
34d20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70  qlite3_value] sp
34d30 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70  ecified in the p
34d40 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61  arameter may cha
34d50 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61  nge or.** be dea
34d60 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73  llocated after s
34d70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
34d80 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69  lue() returns wi
34d90 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
34da0 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  A [protected sql
34db0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34dc0 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65  ct may always be
34dd0 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a   used where an.*
34de0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
34df0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34e00 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64  ject is required
34e10 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b  , so either.** k
34e20 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ind of [sqlite3_
34e30 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61  value] object ca
34e40 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74  n be used with t
34e50 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  his interface..*
34e60 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f  *.** If these ro
34e70 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
34e80 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68  d from within th
34e90 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  e different thre
34ea0 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f  ad.** than the o
34eb0 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ne containing th
34ec0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
34ed0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
34ee0 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20  hat received.** 
34ef0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
34f00 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74  text] pointer, t
34f10 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
34f20 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c  ndefined..*/.SQL
34f30 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
34f40 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
34f50 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34f60 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
34f70 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
34f80 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
34f90 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
34fa0 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69  sult_double(sqli
34fb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f  te3_context*, do
34fc0 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50  uble);.SQLITE_AP
34fd0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
34fe0 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
34ff0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
35000 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
35010 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
35020 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35030 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
35040 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
35050 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  void*, int);.SQL
35060 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
35070 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35080 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
35090 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
350a0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
350b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
350c0 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63  _nomem(sqlite3_c
350d0 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
350e0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
350f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
35100 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ode(sqlite3_cont
35110 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  ext*, int);.SQLI
35120 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
35130 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
35140 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35150 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
35160 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
35170 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
35180 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
35190 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51  lite3_int64);.SQ
351a0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
351b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
351c0 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  l(sqlite3_contex
351d0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
351e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
351f0 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ult_text(sqlite3
35200 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
35210 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69   char*, int, voi
35220 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
35230 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
35240 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35250 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
35260 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
35270 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
35280 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
35290 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
352a0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
352b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
352c0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
352d0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
352e0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
352f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35300 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
35310 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
35320 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
35330 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
35340 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
35350 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35360 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
35370 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
35380 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
35390 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
353a0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
353b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
353c0 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  *, int n);../*.*
353d0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69  * CAPI3REF: Defi
353e0 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67  ne New Collating
353f0 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a   Sequences.**.**
35400 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
35410 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f  s add, remove, o
35420 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c  r modify a [coll
35430 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65  ation] associate
35440 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  d.** with the [d
35450 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35460 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73  on] specified as
35470 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
35480 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
35490 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c  name of the coll
354a0 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38  ation is a UTF-8
354b0 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
354c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
354d0 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
354e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
354f0 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
35500 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
35510 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
35520 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  e order for sqli
35530 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35540 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f  tion16()..** ^Co
35550 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68  llation names th
35560 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c  at compare equal
35570 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73   according to [s
35580 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28  qlite3_strnicmp(
35590 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64  )] are.** consid
355a0 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73  ered to be the s
355b0 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ame name..**.** 
355c0 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75  ^(The third argu
355d0 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20  ment (eTextRep) 
355e0 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74  must be one of t
355f0 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a  he constants:.**
35600 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
35610 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
35620 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
35630 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  16LE],.** <li> [
35640 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
35650 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
35660 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c  _UTF16], or.** <
35670 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
35680 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c  6_ALIGNED]..** <
35690 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65  /ul>)^.** ^The e
356a0 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
356b0 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
356c0 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69  encoding of stri
356d0 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f  ngs passed.** to
356e0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
356f0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
35700 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  , xCallback..** 
35710 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  ^The [SQLITE_UTF
35720 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  16] and [SQLITE_
35730 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
35740 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52  alues for eTextR
35750 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69  ep.** force stri
35760 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20  ngs to be UTF16 
35770 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65  with native byte
35780 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20   order..** ^The 
35790 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
357a0 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72  IGNED] value for
357b0 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73   eTextRep forces
357c0 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69   strings to begi
357d0 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20  n.** on an even 
357e0 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a  byte address..**
357f0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
35800 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20  argument, pArg, 
35810 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  is an applicatio
35820 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74  n data pointer t
35830 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a  hat is passed.**
35840 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
35850 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
35860 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
35870 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
35880 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  k..**.** ^The fi
35890 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43  fth argument, xC
358a0 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f  allback, is a po
358b0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c  inter to the col
358c0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e  lating function.
358d0 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f  .** ^Multiple co
358e0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
358f0 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65  s can be registe
35900 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61  red using the sa
35910 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77  me name but.** w
35920 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54  ith different eT
35930 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72  extRep parameter
35940 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c  s and SQLite wil
35950 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a  l use whichever.
35960 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ** function requ
35970 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  ires the least a
35980 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72  mount of data tr
35990 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a  ansformation..**
359a0 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61   ^If the xCallba
359b0 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e  ck argument is N
359c0 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c  ULL then the col
359d0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
359e0 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20  is.** deleted.  
359f0 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74  ^When all collat
35a00 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61  ing functions ha
35a10 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  ving the same na
35a20 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a  me are deleted,.
35a30 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f  ** that collatio
35a40 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75  n is no longer u
35a50 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  sable..**.** ^Th
35a60 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
35a70 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73  tion callback is
35a80 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
35a90 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67  copy of the pArg
35aa0 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e   .** application
35ab0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e   data pointer an
35ac0 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e  d with two strin
35ad0 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69  gs in the encodi
35ae0 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ng specified.** 
35af0 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20  by the eTextRep 
35b00 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63  argument.  The c
35b10 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35b20 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e  n must return an
35b30 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74  .** integer that
35b40 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65   is negative, ze
35b50 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a  ro, or positive.
35b60 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20  ** if the first 
35b70 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74  string is less t
35b80 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f  han, equal to, o
35b90 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  r greater than t
35ba0 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65  he second,.** re
35bb0 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63  spectively.  A c
35bc0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35bd0 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65  n must always re
35be0 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e  turn the same an
35bf0 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68  swer.** given th
35c00 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20  e same inputs.  
35c10 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63  If two or more c
35c20 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35c30 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65  ns are registere
35c40 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65  d.** to the same
35c50 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20   collation name 
35c60 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74  (using different
35c70 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73   eTextRep values
35c80 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75  ) then all.** mu
35c90 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76  st give an equiv
35ca0 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65  alent answer whe
35cb0 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65  n invoked with e
35cc0 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67  quivalent string
35cd0 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74  s..** The collat
35ce0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
35cf0 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f  t obey the follo
35d00 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20  wing properties 
35d10 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e  for all.** strin
35d20 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a  gs A, B, and C:.
35d30 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
35d40 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20  i> If A==B then 
35d50 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  B==A..** <li> If
35d60 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74   A==B and B==C t
35d70 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69  hen A==C..** <li
35d80 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e  > If A&lt;B THEN
35d90 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e   B&gt;A..** <li>
35da0 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42   If A&lt;B and B
35db0 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b  &lt;C then A&lt;
35dc0 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  C..** </ol>.**.*
35dd0 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67  * If a collating
35de0 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20   function fails 
35df0 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65  any of the above
35e00 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64   constraints and
35e10 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69   that.** collati
35e20 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20  ng function is  
35e30 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75  registered and u
35e40 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  sed, then the be
35e50 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
35e60 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
35e70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
35e80 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
35e90 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73  ation_v2() works
35ea0 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72   like sqlite3_cr
35eb0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
35ec0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64  .** with the add
35ed0 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78  ition that the x
35ee0 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
35ef0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70   is invoked on p
35f00 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  Arg when.** the 
35f10 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
35f20 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a  on is deleted..*
35f30 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  * ^Collating fun
35f40 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74  ctions are delet
35f50 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65  ed when they are
35f60 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c   overridden by l
35f70 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  ater.** calls to
35f80 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63   the collation c
35f90 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  reation function
35fa0 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a  s or when the.**
35fb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35fc0 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64  ction] is closed
35fd0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
35fe0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
35ff0 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61  ^The xDestroy ca
36000 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74  llback is <u>not
36010 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74  </u> called if t
36020 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  he .** sqlite3_c
36030 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
36040 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61  v2() function fa
36050 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ils.  Applicatio
36060 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a  ns that invoke.*
36070 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
36080 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
36090 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
360a0 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e  xDestroy argumen
360b0 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65  t should .** che
360c0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
360d0 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f  de and dispose o
360e0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
360f0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a  n data pointer.*
36100 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74  * themselves rat
36110 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69  her than expecti
36120 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61  ng SQLite to dea
36130 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68  l with it for th
36140 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64  em..** This is d
36150 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76  ifferent from ev
36160 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  ery other SQLite
36170 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
36180 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a   inconsistency .
36190 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74  ** is unfortunat
361a0 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20  e but cannot be 
361b0 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20  changed without 
361c0 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72  breaking backwar
361d0 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  ds .** compatibi
361e0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  lity..**.** See 
361f0 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f  also:  [sqlite3_
36200 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
36210 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
36220 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
36230 64 31 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  d16()]..*/.SQLIT
36240 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
36250 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36260 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
36270 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
36280 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
36290 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
362a0 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
362b0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
362c0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
362d0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
362e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
362f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36300 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
36310 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
36320 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
36330 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
36340 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
36350 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
36360 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
36370 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
36380 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  void*),.  void(*
36390 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
363a0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
363b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
363c0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
363d0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
363e0 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
363f0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
36400 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
36410 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
36420 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
36430 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
36440 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
36450 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
36460 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
36470 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f  lbacks.**.** ^To
36480 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
36490 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
364a0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
364b0 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
364c0 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
364d0 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
364e0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
364f0 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
36500 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
36510 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36520 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  n] to be invoked
36530 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
36540 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
36550 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
36560 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
36570 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
36580 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
36590 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
365a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
365b0 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
365c0 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
365d0 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
365e0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
365f0 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
36600 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
36610 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c  n UTF-8. ^If sql
36620 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
36630 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
36640 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
36650 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
36660 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
36670 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
36680 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  r..** ^A call to
36690 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
366a0 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78   replaces the ex
366b0 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e  isting collation
366c0 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b  -needed callback
366d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74  ..**.** ^(When t
366e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
366f0 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
36700 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
36710 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
36720 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
36730 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
36740 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
36750 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
36760 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
36770 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
36780 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
36790 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
367a0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
367b0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
367c0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
367d0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
367e0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
367f0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
36800 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
36810 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
36820 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
36830 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
36840 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
36850 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
36860 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
36870 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
36880 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
36890 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e  tion sequence.)^
368a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
368b0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
368c0 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
368d0 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
368e0 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
368f0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36900 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
36910 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36920 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
36930 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36940 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
36950 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
36960 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
36970 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73  tion_needed(.  s
36980 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
36990 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
369a0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
369b0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
369c0 63 68 61 72 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  char*).);.SQLITE
369d0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
369e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
369f0 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  d16(.  sqlite3*,
36a00 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69   .  void*,.  voi
36a10 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
36a20 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
36a30 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
36a40 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  ..#ifdef SQLITE_
36a50 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20  HAS_CODEC./*.** 
36a60 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20  Specify the key 
36a70 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64  for an encrypted
36a80 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73   database.  This
36a90 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
36aa0 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67  be.** called rig
36ab0 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ht after sqlite3
36ac0 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  _open()..**.** T
36ad0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
36ae0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
36af0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
36b00 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
36b10 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
36b20 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
36b30 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79   int sqlite3_key
36b40 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
36b50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36b60 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
36b70 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
36b80 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
36b90 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
36ba0 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
36bb0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
36bc0 20 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28   sqlite3_key_v2(
36bd0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
36be0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36bf0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
36c00 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
36c10 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
36c20 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20  Name,           
36c30 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64  /* Name of the d
36c40 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
36c50 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
36c60 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
36c70 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  he key */.);../*
36c80 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b  .** Change the k
36c90 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61  ey on an open da
36ca0 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
36cb0 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
36cc0 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79   is not.** encry
36cd0 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69  pted, this routi
36ce0 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20  ne will encrypt 
36cf0 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20  it.  If pNew==0 
36d00 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a  or nNew==0, the.
36d10 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64  ** database is d
36d20 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ecrypted..**.** 
36d30 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
36d40 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
36d50 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
36d60 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
36d70 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
36d80 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te..*/.SQLITE_AP
36d90 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  I int sqlite3_re
36da0 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
36db0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
36dc0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
36dd0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
36de0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
36df0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
36e00 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
36e10 65 79 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ey */.);.SQLITE_
36e20 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
36e30 72 65 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69  rekey_v2(.  sqli
36e40 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
36e50 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
36e60 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
36e70 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
36e80 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
36e90 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
36ea0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
36eb0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
36ec0 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
36ed0 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
36ee0 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
36ef0 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
36f00 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
36f10 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20  a SEE database. 
36f20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
36f30 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
36f40 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20  he SEE routines 
36f50 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51  will work..*/.SQ
36f60 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
36f70 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73  lite3_activate_s
36f80 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  ee(.  const char
36f90 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
36fa0 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
36fb0 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
36fc0 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53  #endif..#ifdef S
36fd0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52  QLITE_ENABLE_CER
36fe0 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  OD./*.** Specify
36ff0 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
37000 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20  key for a CEROD 
37010 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73  database.  Unles
37020 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c  s .** activated,
37030 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52   none of the CER
37040 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  OD routines will
37050 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45   work..*/.SQLITE
37060 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
37070 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64  3_activate_cerod
37080 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
37090 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
370a0 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
370b0 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
370c0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
370d0 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78  3REF: Suspend Ex
370e0 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68  ecution For A Sh
370f0 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54  ort Time.**.** T
37100 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  he sqlite3_sleep
37110 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  () function caus
37120 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
37130 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
37140 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f   execution.** fo
37150 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d  r at least a num
37160 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
37170 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e  nds specified in
37180 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a   its parameter..
37190 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65  **.** If the ope
371a0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f  rating system do
371b0 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73  es not support s
371c0 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69  leep requests wi
371d0 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e  th.** millisecon
371e0 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f  d time resolutio
371f0 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65  n, then the time
37200 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64   will be rounded
37210 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65   up to.** the ne
37220 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68  arest second. Th
37230 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
37240 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
37250 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65  p actually.** re
37260 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65  quested from the
37270 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
37280 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  m is returned..*
37290 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70  *.** ^SQLite imp
372a0 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
372b0 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
372c0 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
372d0 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
372e0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
372f0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49  _vfs] object.  I
37300 66 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d  f the xSleep() m
37310 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
37320 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e  default VFS is n
37330 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63  ot implemented c
37340 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74  orrectly, or not
37350 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a   implemented at.
37360 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65  ** all, then the
37370 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
37380 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79  ite3_sleep() may
37390 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68   deviate from th
373a0 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a  e description.**
373b0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
373c0 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a   paragraphs..*/.
373d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
373e0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74  qlite3_sleep(int
373f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37400 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
37410 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
37420 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a  emporary Files.*
37430 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67  *.** ^(If this g
37440 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
37450 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
37460 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
37470 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
37480 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
37490 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
374a0 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72   then all tempor
374b0 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65  ary files.** cre
374c0 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77  ated by SQLite w
374d0 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c  hen using a buil
374e0 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  t-in [sqlite3_vf
374f0 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c  s | VFS].** will
37500 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68   be placed in th
37510 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20  at directory.)^ 
37520 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62   ^If this variab
37530 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  le.** is a NULL 
37540 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
37550 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20  Lite performs a 
37560 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70  search for an ap
37570 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d  propriate.** tem
37580 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65  porary file dire
37590 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ctory..**.** It 
375a0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
375b0 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
375c0 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d  is variable in m
375d0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20  ore than one.** 
375e0 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65  thread at a time
375f0 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  .  It is not saf
37600 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
37610 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
37620 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62  e.** if a [datab
37630 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37640 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74  is being used at
37650 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69   the same time i
37660 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20  n a separate.** 
37670 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73  thread..** It is
37680 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
37690 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
376a0 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
376b0 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
376c0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
376d0 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
376e0 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
376f0 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
37700 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74  een called and t
37710 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
37720 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  e remain unchang
37730 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72  ed.** thereafter
37740 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65  ..**.** ^The [te
37750 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
37760 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d  ry pragma] may m
37770 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
37780 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a  ble and cause.**
37790 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20   it to point to 
377a0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
377b0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
377c0 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72  lloc].  ^Further
377d0 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65  more,.** the [te
377e0 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
377f0 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79  ry pragma] alway
37800 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61  s assumes that a
37810 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61  ny string.** tha
37820 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
37830 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c  points to is hel
37840 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61  d in memory obta
37850 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
37860 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61  qlite3_malloc] a
37870 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61  nd the pragma ma
37880 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65  y attempt to fre
37890 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a  e that memory.**
378a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
378b0 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c  free]..** Hence,
378c0 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   if this variabl
378d0 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69  e is modified di
378e0 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69  rectly, either i
378f0 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d  t should be.** m
37900 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65  ade NULL or made
37910 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
37920 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
37930 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
37940 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68  c].** or else th
37950 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65  e use of the [te
37960 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
37970 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c  ry pragma] shoul
37980 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a  d be avoided..**
37990 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
379a0 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
379b0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
379c0 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
379d0 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
379e0 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
379f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ng [sqlite3_open
37a00 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
37a10 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77 69  en_v2].  Otherwi
37a20 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
37a30 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
37a40 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
37a50 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
37a60 6d 61 79 20 66 61 69 6c 2e 20 20 48 65 72 65 20  may fail.  Here 
37a70 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65  is an.** example
37a80 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20 74 68   of how to do th
37a90 69 73 20 75 73 69 6e 67 20 43 2b 2b 20 77 69 74  is using C++ wit
37aa0 68 20 74 68 65 20 57 69 6e 64 6f 77 73 20 52 75  h the Windows Ru
37ab0 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntime:.**.** <bl
37ac0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
37ad0 2a 20 4c 50 43 57 53 54 52 20 7a 50 61 74 68 20  * LPCWSTR zPath 
37ae0 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61  = Windows::Stora
37af0 67 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44  ge::ApplicationD
37b00 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a  ata::Current->.*
37b10 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 54 65 6d  * &nbsp;     Tem
37b20 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61  poraryFolder->Pa
37b30 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63  th->Data();.** c
37b40 68 61 72 20 7a 50 61 74 68 42 75 66 26 23 39 31  har zPathBuf&#91
37b50 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31 26 23 39  ;MAX_PATH + 1&#9
37b60 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50  3;;.** memset(zP
37b70 61 74 68 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f  athBuf, 0, sizeo
37b80 66 28 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a  f(zPathBuf));.**
37b90 20 57 69 64 65 43 68 61 72 54 6f 4d 75 6c 74 69   WideCharToMulti
37ba0 42 79 74 65 28 43 50 5f 55 54 46 38 2c 20 30 2c  Byte(CP_UTF8, 0,
37bb0 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74   zPath, -1, zPat
37bc0 68 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61  hBuf, sizeof(zPa
37bd0 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70  thBuf),.** &nbsp
37be0 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c  ;     NULL, NULL
37bf0 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65  );.** sqlite3_te
37c00 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 3d 20 73  mp_directory = s
37c10 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
37c20 25 73 22 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a  %s", zPathBuf);.
37c30 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
37c40 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45  quote>.*/.SQLITE
37c50 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45  _API SQLITE_EXTE
37c60 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  RN char *sqlite3
37c70 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b  _temp_directory;
37c80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37c90 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
37ca0 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 44 61 74  lder Holding Dat
37cb0 61 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a  abase Files.**.*
37cc0 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62  * ^(If this glob
37cd0 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
37ce0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
37cf0 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
37d00 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
37d10 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
37d20 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
37d30 65 6e 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20  en all database 
37d40 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69 66 69  files.** specifi
37d50 65 64 20 77 69 74 68 20 61 20 72 65 6c 61 74 69  ed with a relati
37d60 76 65 20 70 61 74 68 6e 61 6d 65 20 61 6e 64 20  ve pathname and 
37d70 63 72 65 61 74 65 64 20 6f 72 20 61 63 63 65 73  created or acces
37d80 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65  sed by.** SQLite
37d90 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75   when using a bu
37da0 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73 20 5b  ilt-in windows [
37db0 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46  sqlite3_vfs | VF
37dc0 53 5d 20 77 69 6c 6c 20 62 65 20 61 73 73 75 6d  S] will be assum
37dd0 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65 6c 61  ed.** to be rela
37de0 74 69 76 65 20 74 6f 20 74 68 61 74 20 64 69 72  tive to that dir
37df0 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20 74 68  ectory.)^ ^If th
37e00 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  is variable is a
37e10 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
37e20 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
37e30 73 75 6d 65 73 20 74 68 61 74 20 61 6c 6c 20 64  sumes that all d
37e40 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 73 70  atabase files sp
37e50 65 63 69 66 69 65 64 0a 2a 2a 20 77 69 74 68 20  ecified.** with 
37e60 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e  a relative pathn
37e70 61 6d 65 20 61 72 65 20 72 65 6c 61 74 69 76 65  ame are relative
37e80 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
37e90 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66 6f 72  directory.** for
37ea0 20 74 68 65 20 70 72 6f 63 65 73 73 2e 20 20 4f   the process.  O
37eb0 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f 77 73 20  nly the windows 
37ec0 56 46 53 20 6d 61 6b 65 73 20 75 73 65 20 6f 66  VFS makes use of
37ed0 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20   this global.** 
37ee0 76 61 72 69 61 62 6c 65 3b 20 69 74 20 69 73 20  variable; it is 
37ef0 69 67 6e 6f 72 65 64 20 62 79 20 74 68 65 20 75  ignored by the u
37f00 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43  nix VFS..**.** C
37f10 68 61 6e 67 69 6e 67 20 74 68 65 20 76 61 6c 75  hanging the valu
37f20 65 20 6f 66 20 74 68 69 73 20 76 61 72 69 61 62  e of this variab
37f30 6c 65 20 77 68 69 6c 65 20 61 20 64 61 74 61 62  le while a datab
37f40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
37f50 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20 72 65  s.** open can re
37f60 73 75 6c 74 20 69 6e 20 61 20 63 6f 72 72 75 70  sult in a corrup
37f70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a  t database..**.*
37f80 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
37f90 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69   to read or modi
37fa0 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
37fb0 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e   in more than on
37fc0 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61  e.** thread at a
37fd0 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f   time.  It is no
37fe0 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
37ff0 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
38000 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b  riable.** if a [
38010 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
38020 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73  ion] is being us
38030 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ed at the same t
38040 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74  ime in a separat
38050 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20  e.** thread..** 
38060 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  It is intended t
38070 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
38080 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a  e be set once.**
38090 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63   as part of proc
380a0 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
380b0 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e  on and before an
380c0 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
380d0 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68  ce.** routines h
380e0 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
380f0 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61  and that this va
38100 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e  riable remain un
38110 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65  changed.** there
38120 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  after..**.** ^Th
38130 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69  e [data_store_di
38140 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
38150 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20  may modify this 
38160 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75  variable and cau
38170 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e  se.** it to poin
38180 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
38190 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
381a0 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75  e3_malloc].  ^Fu
381b0 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68  rthermore,.** th
381c0 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69  e [data_store_di
381d0 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
381e0 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74  always assumes t
381f0 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a  hat any string.*
38200 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  * that this vari
38210 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69  able points to i
38220 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79  s held in memory
38230 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
38240 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
38250 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67  oc] and the prag
38260 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74  ma may attempt t
38270 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f  o free that memo
38280 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ry.** using [sql
38290 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48  ite3_free]..** H
382a0 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61  ence, if this va
382b0 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69  riable is modifi
382c0 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74  ed directly, eit
382d0 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65  her it should be
382e0 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72  .** made NULL or
382f0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
38300 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
38310 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
38320 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c  malloc].** or el
38330 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  se the use of th
38340 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69  e [data_store_di
38350 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
38360 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65  should be avoide
38370 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
38380 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63   SQLITE_EXTERN c
38390 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 61 74  har *sqlite3_dat
383a0 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  a_directory;../*
383b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
383c0 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d  st For Auto-Comm
383d0 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f  it Mode.** KEYWO
383e0 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74  RDS: {autocommit
383f0 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68   mode}.**.** ^Th
38400 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
38410 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72  tocommit() inter
38420 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e  face returns non
38430 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f  -zero or.** zero
38440 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61   if the given da
38450 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38460 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69  n is or is not i
38470 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  n autocommit mod
38480 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  e,.** respective
38490 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ly.  ^Autocommit
384a0 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64   mode is on by d
384b0 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f  efault..** ^Auto
384c0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64  commit mode is d
384d0 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45  isabled by a [BE
384e0 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  GIN] statement..
384f0 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  ** ^Autocommit m
38500 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65  ode is re-enable
38510 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20  d by a [COMMIT] 
38520 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a  or [ROLLBACK]..*
38530 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20  *.** If certain 
38540 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20  kinds of errors 
38550 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65  occur on a state
38560 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75  ment within a mu
38570 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  lti-statement.**
38580 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72   transaction (er
38590 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
385a0 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
385b0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a  QLITE_IOERR],.**
385c0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c   [SQLITE_NOMEM],
385d0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
385e0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  and [SQLITE_INTE
385f0 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65  RRUPT]) then the
38600 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
38610 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20  might be rolled 
38620 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
38630 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61  ly.  The only wa
38640 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74  y to.** find out
38650 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20   whether SQLite 
38660 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
38670 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72  lled back the tr
38680 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a  ansaction after.
38690 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74  ** an error is t
386a0 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74  o use this funct
386b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ion..**.** If an
386c0 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61  other thread cha
386d0 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d  nges the autocom
386e0 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68  mit status of th
386f0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
38700 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
38710 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
38720 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  unning, then the
38730 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
38740 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
38750 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
38760 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
38770 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
38780 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38790 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 6