/ Hex Artifact Content
Login

Artifact 0abc2ddd9601e530b471847c73a4379ab50854b6:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  y are supported 
07d0: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
07e0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
07f0: 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
0800: 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64  n writers should
0810: 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a   be aware that.*
0820: 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  * experimental i
0830: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75  nterfaces are su
0840: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
0850: 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65  in point release
0860: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d  s..**.** These m
0870: 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65  acros used to re
0880: 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73  solve to various
0890: 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c   kinds of compil
08a0: 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a  er magic that.**
08b0: 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20   would generate 
08c0: 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73  warning messages
08d0: 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65 20   when they were 
08e0: 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a  used.  But that.
08f0: 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69  ** compiler magi
0900: 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72  c ended up gener
0910: 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75  ating such a flu
0920: 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72  rry of bug repor
0930: 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61  ts.** that we ha
0940: 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20  ve taken it all 
0950: 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63  out and gone bac
0960: 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c  k to using simpl
0970: 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73  e.** noop macros
0980: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
0990: 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23  ITE_DEPRECATED.#
09a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
09b0: 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a  PERIMENTAL../*.*
09c0: 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20 73  * Ensure these s
09d0: 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20  ymbols were not 
09e0: 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20  defined by some 
09f0: 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 20  previous header 
0a00: 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  file..*/.#ifdef 
0a10: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23  SQLITE_VERSION.#
0a20: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0a30: 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66  RSION.#endif.#if
0a40: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0a50: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65  ON_NUMBER.# unde
0a60: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a70: 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a  _NUMBER.#endif..
0a80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
0a90: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62  Compile-Time Lib
0aa0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0ab0: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  bers.**.** ^(The
0ac0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ad0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0ae0: 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71   macro in the sq
0af0: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a  lite3.h header.*
0b00: 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61  * evaluates to a
0b10: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20   string literal 
0b20: 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69  that is the SQLi
0b30: 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68  te version in th
0b40: 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59  e.** format "X.Y
0b50: 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20 74  .Z" where X is t
0b60: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e  he major version
0b70: 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20   number (always 
0b80: 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33  3 for.** SQLite3
0b90: 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d  ) and Y is the m
0ba0: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  inor version num
0bb0: 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65  ber and Z is the
0bc0: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e   release number.
0bd0: 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  )^.** ^(The [SQL
0be0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bf0: 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ER] C preprocess
0c00: 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65  or macro resolve
0c10: 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  s to an integer.
0c20: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c 75  ** with the valu
0c30: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0c40: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0c50: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65   X, Y, and Z are
0c60: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d   the same.** num
0c70: 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51  bers used in [SQ
0c80: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e  LITE_VERSION].)^
0c90: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56  .** The SQLITE_V
0ca0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f  ERSION_NUMBER fo
0cb0: 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65  r any given rele
0cc0: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ase of SQLite wi
0cd0: 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61  ll also.** be la
0ce0: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72 65  rger than the re
0cf0: 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  lease from which
0d00: 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e 20   it is derived. 
0d10: 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a   Either Y will.*
0d20: 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61  * be held consta
0d30: 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  nt and Z will be
0d40: 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20   incremented or 
0d50: 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69  else Y will be i
0d60: 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e  ncremented.** an
0d70: 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65  d Z will be rese
0d80: 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t to zero..**.**
0d90: 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33   Since version 3
0da0: 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f  .6.18, SQLite so
0db0: 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 62 65  urce code has be
0dc0: 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  en stored in the
0dd0: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74  .** <a href="htt
0de0: 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73  p://www.fossil-s
0df0: 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20  cm.org/">Fossil 
0e00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0e10: 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74  nagement.** syst
0e20: 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51  em</a>.  ^The SQ
0e30: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d  LITE_SOURCE_ID m
0e40: 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74  acro evaluates t
0e50: 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68  o.** a string wh
0e60: 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 20 61  ich identifies a
0e70: 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 65 63   particular chec
0e80: 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a  k-in of SQLite.*
0e90: 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e  * within its con
0ea0: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67  figuration manag
0eb0: 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e  ement system.  ^
0ec0: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  The SQLITE_SOURC
0ed0: 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63  E_ID.** string c
0ee0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 65  ontains the date
0ef0: 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65   and time of the
0f00: 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20   check-in (UTC) 
0f10: 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68  and an SHA1.** h
0f20: 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72  ash of the entir
0f30: 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a  e source tree..*
0f40: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
0f50: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0f60: 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  on()],.** [sqlit
0f70: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
0f80: 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65  mber()], [sqlite
0f90: 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a  3_sourceid()],.*
0fa0: 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  * [sqlite_versio
0fb0: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
0fc0: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
0fd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
0fe0: 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20  _VERSION        
0ff0: 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69  "--VERS--".#defi
1000: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
1010: 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49  N_NUMBER --VERSI
1020: 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66  ON-NUMBER--.#def
1030: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1040: 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55  E_ID      "--SOU
1050: 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a  RCE-ID--"../*.**
1060: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
1070: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
1080: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
1090: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10a0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
10b0: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
10c0: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
10d0: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
10e0: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
10f0: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1100: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1110: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1120: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1130: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1140: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
1150: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
1160: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1170: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
1180: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
1190: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11a0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
11b0: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
11c0: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
11d0: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
11e0: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
11f0: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1200: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1210: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1220: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1230: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1240: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
1250: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
1260: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
1270: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
1280: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
1290: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12a0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
12b0: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
12c0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
12d0: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
12e0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
12f0: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1300: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1310: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1320: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1330: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1340: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
1350: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
1360: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
1370: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1380: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
1390: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13a0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
13b0: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
13c0: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
13d0: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
13e0: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
13f0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1400: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1410: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1420: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1430: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1440: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
1450: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
1460: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
1470: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
1480: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
1490: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14a0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
14b0: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
14c0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
14d0: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
14e0: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
14f0: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1500: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1510: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1520: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1530: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1540: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
1550: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
1560: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
1570: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
1580: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
1590: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15a0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
15b0: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
15c0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
15d0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
15e0: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
15f0: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1600: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1610: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1620: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ()]..*/.SQLITE_E
1630: 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72  XTERN const char
1640: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
1650: 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  [];.const char *
1660: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1670: 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20  on(void);.const 
1680: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1690: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e  urceid(void);.in
16a0: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  t sqlite3_libver
16b0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
16c0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16d0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
16e0: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e  rary Compilation
16f0: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73   Options Diagnos
1700: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tics.**.** ^The 
1710: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1720: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e  ption_used() fun
1730: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20  ction returns 0 
1740: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74  or 1 .** indicat
1750: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20  ing whether the 
1760: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e  specified option
1770: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20   was defined at 
1780: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
1790: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
17a0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d  prefix may be om
17b0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a  itted from the .
17c0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70  ** option name p
17d0: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
17e0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
17f0: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  sed().  .**.** ^
1800: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
1810: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1820: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  function allows 
1830: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65  iterating.** ove
1840: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70  r the list of op
1850: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20  tions that were 
1860: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69  defined at compi
1870: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65  le time by.** re
1880: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68  turning the N-th
1890: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70   compile time op
18a0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49  tion string.  ^I
18b0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
18c0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  nge,.** sqlite3_
18d0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
18e0: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  t() returns a NU
18f0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
1900: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72  e SQLITE_ .** pr
1910: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20  efix is omitted 
1920: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73  from any strings
1930: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
1940: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1950: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a  option_get()..**
1960: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72  .** ^Support for
1970: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20   the diagnostic 
1980: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65  functions sqlite
1990: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
19a0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71  used().** and sq
19b0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
19c0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65  ion_get() may be
19d0: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63   omitted by spec
19e0: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b  ifying the .** [
19f0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1a00: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d  ILEOPTION_DIAGS]
1a10: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69   option at compi
1a20: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53  le time..**.** S
1a30: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e  ee also: SQL fun
1a40: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63  ctions [sqlite_c
1a50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1a60: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1a70: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1a80: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65  n_get()] and the
1a90: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e   [compile_option
1aa0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69  s pragma]..*/.#i
1ab0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
1ac0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
1ad0: 44 49 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65  DIAGS.int sqlite
1ae0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1af0: 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20  used(const char 
1b00: 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73  *zOptName);.cons
1b10: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1b20: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b30: 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66  t(int N);.#endif
1b40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b50: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1b60: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1b70: 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a  Threadsafe.**.**
1b80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68   ^The sqlite3_th
1b90: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
1ba0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ion returns zero
1bb0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
1bc0: 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  ** SQLite was co
1bd0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
1be0: 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65  xing code omitte
1bf0: 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20  d due to the.** 
1c00: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1c10: 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  FE] compile-time
1c20: 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65   option being se
1c30: 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51  t to 0..**.** SQ
1c40: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70  Lite can be comp
1c50: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74  iled with or wit
1c60: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57  hout mutexes.  W
1c70: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  hen.** the [SQLI
1c80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43  TE_THREADSAFE] C
1c90: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1ca0: 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d  cro is 1 or 2, m
1cb0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1cc0: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1cd0: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1ce0: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51   When the.** [SQ
1cf0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d00: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a   macro is 0, .**
1d10: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
1d20: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
1d30: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
1d40: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
1d50: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
1d60: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
1d70: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
1d80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
1d90: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
1da0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
1db0: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
1dc0: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
1dd0: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
1de0: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
1df0: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
1e00: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
1e10: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
1e20: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
1e30: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
1e40: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
1e50: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65   ^The default be
1e60: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75  havior is for mu
1e70: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62  texes to be enab
1e80: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  led..**.** This 
1e90: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1ea0: 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c   used by an appl
1eb0: 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20  ication to make 
1ec0: 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1ed0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
1ee0: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69  te that it is li
1ef0: 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61  nking against wa
1f00: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
1f10: 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73  ** the desired s
1f20: 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53  etting of the [S
1f30: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f40: 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54  ] macro..**.** T
1f50: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  his interface on
1f60: 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68  ly reports on th
1f70: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
1f80: 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20  utex setting.** 
1f90: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1fa0: 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e  HREADSAFE] flag.
1fb0: 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
1fc0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
1fd0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fe0: 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d  E=1 or =2 then m
1ff0: 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c  utexes are enabl
2000: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75  ed by default bu
2010: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c  t.** can be full
2020: 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64  y or partially d
2030: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
2040: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2050: 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69  _config()].** wi
2060: 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51  th the verbs [SQ
2070: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2080: 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49  LETHREAD], [SQLI
2090: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
20a0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  HREAD],.** or [S
20b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
20c0: 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75  EX].  ^(The retu
20d0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a  rn value of the.
20e0: 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  ** sqlite3_threa
20f0: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
2100: 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20   shows only the 
2110: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74  compile-time set
2120: 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61  ting of.** threa
2130: 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e  d safety, not an
2140: 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67  y run-time chang
2150: 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74 69  es to that setti
2160: 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71  ng made by.** sq
2170: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20  lite3_config(). 
2180: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2190: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
21a0: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68   from sqlite3_th
21b0: 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73  readsafe().** is
21c0: 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61   unchanged by ca
21d0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
21e0: 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  onfig().)^.**.**
21f0: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64   See the [thread
2200: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65  ing mode] docume
2210: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
2220: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
2230: 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  on..*/.int sqlit
2240: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f  e3_threadsafe(vo
2250: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
2260: 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
2270: 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65  onnection Handle
2280: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
2290: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22a0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
22b0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
22c0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
22d0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
22e0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
22f0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
2300: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
2310: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
2320: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
2330: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
2340: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
2350: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
2360: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
2370: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
2380: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
2390: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
23a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
23b0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
23c0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
23d0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
23e0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
23f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2400: 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73  se_v2()] are its
2410: 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54   destructors.  T
2420: 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74  here are many ot
2430: 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  her.** interface
2440: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2450: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2460: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
2470: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2480: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2490: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
24a0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
24b0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
24c0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
24d0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
24e0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
24f0: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
2500: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
2510: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2520: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2530: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2540: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2550: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2560: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
2570: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
2580: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
2590: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
25a0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
25b0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
25c0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
25d0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
25e0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
25f0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
2600: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
2610: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2620: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2630: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2640: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2650: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2660: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
2670: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
2680: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
2690: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
26a0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
26b0: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
26c0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
26d0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
26e0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
26f0: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
2700: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2710: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2720: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2730: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2740: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2750: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2760: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
2770: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
2780: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
2790: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
27a0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
27b0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
27c0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
27d0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
27e0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
27f0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
2800: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
2810: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2820: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2830: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2840: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2850: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2860: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2870: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2880: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2890: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
28a0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
28b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
28c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
28d0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
28e0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
28f0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
2900: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
2910: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2920: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2930: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2940: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2950: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2960: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2970: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2980: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2990: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
29a0: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
29b0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
29c0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
29d0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
29e0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
29f0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2a00: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
2a10: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2a20: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
2a30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2a40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
2a50: 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73  se_v2() routines
2a60: 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 73   are destructors
2a70: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  .** for the [sql
2a80: 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ite3] object..**
2a90: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
2aa0: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73  e3_close() and s
2ab0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2ac0: 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  ) return [SQLITE
2ad0: 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b  _OK] if.** the [
2ae0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2af0: 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  is successfully 
2b00: 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c  destroyed and al
2b10: 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  l associated.** 
2b20: 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64 65  resources are de
2b30: 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  allocated..**.**
2b40: 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
2b50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2b60: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2b70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2b80: 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2b90: 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  ts or unfinished
2ba0: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2bb0: 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c  objects then sql
2bc0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20  ite3_close().** 
2bd0: 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64  will leave the d
2be0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2bf0: 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75  on open and retu
2c00: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
2c10: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
2c20: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63  _close_v2() is c
2c30: 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e  alled with unfin
2c40: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 20  alized prepared 
2c50: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e  statements.** an
2c60: 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20  d/or unfinished 
2c70: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c  sqlite3_backups,
2c80: 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
2c90: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  se connection be
2ca0: 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73  comes.** an unus
2cb0: 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68  able "zombie" wh
2cc0: 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ich will automat
2cd0: 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f  ically be deallo
2ce0: 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a  cated when the.*
2cf0: 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 20  * last prepared 
2d00: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e  statement is fin
2d10: 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61  alized or the la
2d20: 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  st sqlite3_backu
2d30: 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64  p is.** finished
2d40: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  .  The sqlite3_c
2d50: 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66  lose_v2() interf
2d60: 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ace is intended 
2d70: 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20  for use with.** 
2d80: 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74  host languages t
2d90: 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65 20  hat are garbage 
2da0: 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77  collected, and w
2db0: 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20 69  here the order i
2dc0: 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72  n which.** destr
2dd0: 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65  uctors are calle
2de0: 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a  d is arbitrary..
2df0: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
2e00: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
2e10: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
2e20: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
2e30: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2e40: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2e50: 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73  lob_close | clos
2e60: 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e  e] all [BLOB han
2e70: 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b  dles], and .** [
2e80: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66  sqlite3_backup_f
2e90: 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20  inish | finish] 
2ea0: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  all [sqlite3_bac
2eb0: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73  kup] objects ass
2ec0: 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
2ed0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2ee0: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
2ef0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
2f00: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e  e the object.  ^
2f10: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c  If.** sqlite3_cl
2f20: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  ose_v2() is call
2f30: 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73  ed on a [databas
2f40: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
2f50: 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20  at still has.** 
2f60: 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65  outstanding [pre
2f70: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2f80: 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ], [BLOB handles
2f90: 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71  ], and/or.** [sq
2fa0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2fb0: 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72 65  jects then it re
2fc0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
2fd0: 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f  ] and the deallo
2fe0: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73  cation.** of res
2ff0: 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72 72  ources is deferr
3000: 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72  ed until all [pr
3010: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3020: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3030: 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  s],.** and [sqli
3040: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
3050: 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73  cts are also des
3060: 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  troyed..**.** ^I
3070: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  f an [sqlite3] o
3080: 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79  bject is destroy
3090: 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73  ed while a trans
30a0: 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a  action is open,.
30b0: 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ** the transacti
30c0: 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  on is automatica
30d0: 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  lly rolled back.
30e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72  .**.** The C par
30f0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
3100: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64  e3_close(C)] and
3110: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
3120: 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  v2(C)].** must b
3130: 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a  e either a NULL.
3140: 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e  ** pointer or an
3150: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3160: 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e  t pointer obtain
3170: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
3180: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
3190: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
31a0: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
31b0: 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
31c0: 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63  not previously c
31d0: 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69  losed..** ^Calli
31e0: 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  ng sqlite3_close
31f0: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c  () or sqlite3_cl
3200: 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 20  ose_v2() with a 
3210: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
3220: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61  argument is a ha
3230: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f  rmless no-op..*/
3240: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f  .int sqlite3_clo
3250: 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e  se(sqlite3*);.in
3260: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  t sqlite3_close_
3270: 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  v2(sqlite3*);../
3280: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
3290: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
32a0: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
32b0: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
32c0: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
32d0: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
32e0: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
32f0: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
3300: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
3310: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
3320: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
3330: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
3340: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
3350: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
3360: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
3370: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
3380: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
3390: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
33a0: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
33b0: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
33c0: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
33d0: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
33e0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
33f0: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
3400: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
3410: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
3420: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
3430: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
3440: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
3450: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3460: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3470: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3480: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3490: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
34a0: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
34b0: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
34c0: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
34d0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
34e0: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
34f0: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
3500: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
3510: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
3520: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
3530: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
3540: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
3550: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3560: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3570: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3580: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3590: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
35a0: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
35b0: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
35c0: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
35d0: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
35e0: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
35f0: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
3600: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
3610: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3620: 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67  s relayed throug
3630: 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67  h to the 1st arg
3640: 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a  ument of each.**
3650: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61   callback invoca
3660: 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63  tion.  ^If the c
3670: 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20  allback pointer 
3680: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3690: 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ).** is NULL, th
36a0: 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69  en no callback i
36b0: 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61  s ever invoked a
36c0: 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61  nd result rows a
36d0: 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a  re.** ignored..*
36e0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f  *.** ^If an erro
36f0: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65  r occurs while e
3700: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51  valuating the SQ
3710: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
3720: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  sed into.** sqli
3730: 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e  te3_exec(), then
3740: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
3750: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d  e current statem
3760: 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a  ent stops and.**
3770: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74   subsequent stat
3780: 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70  ements are skipp
3790: 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68  ed.  ^If the 5th
37a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
37b0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
37c0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
37d0: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
37e0: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
37f0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
3800: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
3810: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
3820: 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  d passed back th
3830: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
3840: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61  rameter..** To a
3850: 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  void memory leak
3860: 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  s, the applicati
3870: 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65  on should invoke
3880: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3890: 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65  ].** on error me
38a0: 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65  ssage strings re
38b0: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
38c0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
38d0: 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65   of.** of sqlite
38e0: 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74  3_exec() after t
38f0: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
3900: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f   string is no lo
3910: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20  nger needed..** 
3920: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
3930: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3940: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3950: 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72  ULL and no error
3960: 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e  s.** occur, then
3970: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3980: 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72  sets the pointer
3990: 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61   in its 5th para
39a0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c  meter to.** NULL
39b0: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
39c0: 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  g..**.** ^If an 
39d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
39e0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
39f0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71  non-zero, the sq
3a00: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3a10: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
3a20: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74  SQLITE_ABORT wit
3a30: 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  hout invoking th
3a40: 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e  e callback again
3a50: 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20   and.** without 
3a60: 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73  running any subs
3a70: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
3a80: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
3a90: 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  e 2nd argument t
3aa0: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
3ab0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75  ec() callback fu
3ac0: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a  nction is the.**
3ad0: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
3ae0: 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
3af0: 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75  .  ^The 3rd argu
3b00: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
3b10: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61  te3_exec().** ca
3b20: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
3b30: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3b40: 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e  o strings obtain
3b50: 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a  ed as if from.**
3b60: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
3b70: 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f  _text()], one fo
3b80: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20  r each column.  
3b90: 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f  ^If an element o
3ba0: 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  f a.** result ro
3bb0: 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  w is NULL then t
3bc0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
3bd0: 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
3be0: 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  for the.** sqlit
3bf0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3c00: 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ck is a NULL poi
3c10: 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20  nter.  ^The 4th 
3c20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
3c30: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3c40: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  ) callback is an
3c50: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3c60: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68  rs to strings wh
3c70: 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72  ere each.** entr
3c80: 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65  y represents the
3c90: 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70   name of corresp
3ca0: 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f  onding result co
3cb0: 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64  lumn as obtained
3cc0: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3cd0: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
3ce0: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
3cf0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
3d00: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3d10: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
3d20: 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  r, a pointer.** 
3d30: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
3d40: 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ng, or a pointer
3d50: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f   that contains o
3d60: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
3d70: 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f  nd/or .** SQL co
3d80: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20  mments, then no 
3d90: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
3da0: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
3db0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
3dc0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e   is not changed.
3dd0: 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69  .**.** Restricti
3de0: 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ons:.**.** <ul>.
3df0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3e00: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73  ication must ins
3e10: 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74  ure that the 1st
3e20: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3e30: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3e40: 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20       is a valid 
3e50: 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  and open [databa
3e60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
3e70: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3e80: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3e90: 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61   close the [data
3ea0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
3eb0: 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
3ec0: 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61        the 1st pa
3ed0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3ee0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
3ef0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3f00: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c  s running..** <l
3f10: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3f20: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69  on must not modi
3f30: 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  fy the SQL state
3f40: 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64  ment text passed
3f50: 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68   into.**      th
3f60: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
3f70: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3f80: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
3f90: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
3fa0: 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69  g..** </ul>.*/.i
3fb0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
3fc0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3ff0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
4000: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
4010: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
4040: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4050: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4060: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4070: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4080: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4090: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
40c0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
40d0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
40e0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
4110: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
4120: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
4130: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
4140: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4150: 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64  RDS: {result cod
4160: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a  e definitions}.*
4170: 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65  *.** Many SQLite
4180: 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
4190: 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73  n an integer res
41a0: 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68  ult code from th
41b0: 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68  e set shown.** h
41c0: 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ere in order to 
41d0: 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73 73  indicate success
41e0: 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a   or failure..**.
41f0: 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64  ** New error cod
4200: 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
4210: 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
4220: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
4230: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65  .** See also: [e
4240: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4250: 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d  ode definitions]
4260: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4270: 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20  TE_OK           
4280: 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75  0   /* Successfu
4290: 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62  l result */./* b
42a0: 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f  eginning-of-erro
42b0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69  r-codes */.#defi
42c0: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  ne SQLITE_ERROR 
42d0: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51         1   /* SQ
42e0: 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69  L error or missi
42f0: 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ng database */.#
4300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4310: 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f  TERNAL     2   /
4320: 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63  * Internal logic
4330: 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65   error in SQLite
4340: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4350: 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20  TE_PERM         
4360: 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65  3   /* Access pe
4370: 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20  rmission denied 
4380: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4390: 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34  E_ABORT        4
43a0: 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72     /* Callback r
43b0: 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64  outine requested
43c0: 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65   an abort */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
43e0: 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20           5   /* 
43f0: 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  The database fil
4400: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
4410: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4420: 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f  CKED       6   /
4430: 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65  * A table in the
4440: 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63   database is loc
4450: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4460: 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20  QLITE_NOMEM     
4470: 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c     7   /* A mall
4480: 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23  oc() failed */.#
4490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
44a0: 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f  ADONLY     8   /
44b0: 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69  * Attempt to wri
44c0: 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61  te a readonly da
44d0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
44e0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55  e SQLITE_INTERRU
44f0: 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65  PT    9   /* Ope
4500: 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65  ration terminate
4510: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74  d by sqlite3_int
4520: 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69  errupt()*/.#defi
4530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  ne SQLITE_IOERR 
4540: 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f        10   /* So
4550: 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20  me kind of disk 
4560: 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72  I/O error occurr
4570: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4580: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20  LITE_CORRUPT    
4590: 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74   11   /* The dat
45a0: 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65  abase disk image
45b0: 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f   is malformed */
45c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
45d0: 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20  NOTFOUND    12  
45e0: 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f   /* Unknown opco
45f0: 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69  de in sqlite3_fi
4600: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a  le_control() */.
4610: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4620: 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20  ULL        13   
4630: 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69  /* Insertion fai
4640: 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61  led because data
4650: 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a  base is full */.
4660: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4670: 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20  ANTOPEN    14   
4680: 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65  /* Unable to ope
4690: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
46a0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
46b0: 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20  QLITE_PROTOCOL  
46c0: 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61    15   /* Databa
46d0: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
46e0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
46f0: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
4700: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
4710: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
4720: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4730: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
4740: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4750: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
4760: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4770: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
4780: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
4790: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
47a0: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
47b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
47c0: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
47d0: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
47e0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
47f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4800: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
4810: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
4820: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
4830: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
4840: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
4850: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
4860: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
4880: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
4890: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
48a0: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
48b0: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
48c0: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
48d0: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
48e0: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
48f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4900: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
4910: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
4920: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
4930: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
4940: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
4950: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
4960: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
4970: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
4980: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
4990: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
49a0: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
49b0: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
49c0: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
49d0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
49e0: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20   SQLITE_NOTICE  
49f0: 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69      27   /* Noti
4a00: 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73  fications from s
4a10: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4a20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57  #define SQLITE_W
4a30: 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20  ARNING     28   
4a40: 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d  /* Warnings from
4a50: 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a   sqlite3_log() *
4a60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4a70: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
4a80: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4a90: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
4aa0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4ac0: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4ad0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4ae0: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4af0: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4b00: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4b10: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4b20: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4b30: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4b40: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
4b50: 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69  result code defi
4b60: 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49  nitions}.**.** I
4b70: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4b80: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4b90: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4ba0: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33   return one of 3
4bb0: 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65  0 integer.** [re
4bc0: 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f  sult codes].  Ho
4bd0: 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63  wever, experienc
4be0: 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74  e has shown that
4bf0: 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73   many of.** thes
4c00: 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  e result codes a
4c10: 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72  re too coarse-gr
4c20: 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20  ained.  They do 
4c30: 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a  not provide as.*
4c40: 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69  * much informati
4c50: 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d  on about problem
4c60: 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  s as programmers
4c70: 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e   might like.  In
4c80: 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a   an effort to.**
4c90: 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e   address this, n
4ca0: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
4cb0: 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e   SQLite (version
4cc0: 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72   3.3.8 and later
4cd0: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
4ce0: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
4cf0: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
4d00: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
4d10: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
4d20: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
4d30: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
4d40: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4d50: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
4d60: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
4d70: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
4d80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
4d90: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
4da0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
4db0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
4dc0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
4dd0: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
4de0: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
4df0: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
4e00: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
4e10: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
4e20: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
4e30: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
4e40: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
4e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
4e60: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
4e70: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4e80: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
4e90: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
4ea0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
4eb0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4ec0: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
4ed0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4ee0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
4ef0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f00: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
4f10: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f20: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
4f30: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4f40: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
4f50: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
4f60: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
4f70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f80: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
4f90: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4fa0: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
4fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4fc0: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
4fd0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4fe0: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
4ff0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5000: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
5010: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5020: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
5030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5040: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
5050: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5060: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
5070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5080: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
5090: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50a0: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
50b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50c0: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
50d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50e0: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
50f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5100: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5110: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5120: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5140: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5150: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5160: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5180: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
5190: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
51a0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
51b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
51c0: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
51d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51e0: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<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 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
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 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
5230: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5240: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
5250: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5260: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
5270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5280: 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20  RR_SHMOPEN      
5290: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
52a0: 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64  RR | (18<<8)).#d
52b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
52c0: 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20  RR_SHMSIZE      
52d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
52e0: 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64  RR | (19<<8)).#d
52f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5300: 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20  RR_SHMLOCK      
5310: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5320: 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64  RR | (20<<8)).#d
5330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5340: 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20  RR_SHMMAP       
5350: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5360: 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64  RR | (21<<8)).#d
5370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5380: 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20  RR_SEEK         
5390: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53a0: 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64  RR | (22<<8)).#d
53b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53c0: 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20  RR_DELETE_NOENT 
53d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53e0: 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64  RR | (23<<8)).#d
53f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5400: 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20  RR_MMAP         
5410: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5420: 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64  RR | (24<<8)).#d
5430: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5440: 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20  RR_GETTEMPPATH  
5450: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5460: 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64  RR | (25<<8)).#d
5470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5480: 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  RR_CONVPATH     
5490: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
54a0: 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64  RR | (26<<8)).#d
54b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
54c0: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
54d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
54e0: 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  KED |  (1<<8)).#
54f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5500: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  SY_RECOVERY     
5510: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5520: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a  SY   |  (1<<8)).
5530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
5540: 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20  USY_SNAPSHOT    
5550: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
5560: 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29  USY   |  (2<<8))
5570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5580: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
5590: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
55a0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
55b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
55c0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
55d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
55e0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
55f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5600: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
5610: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
5620: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5630: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5640: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43  QLITE_CANTOPEN_C
5650: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53  ONVPATH       (S
5660: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5670: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5680: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5690: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
56a0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
56b0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
56c0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
56d0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
56e0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
56f0: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5700: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5710: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5720: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5730: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5740: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5750: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5760: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5770: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5780: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5790: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
57a0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
57b0: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
57c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
57d0: 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20  _ABORT_ROLLBACK 
57e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
57f0: 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29  _ABORT | (2<<8))
5800: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5810: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b  CONSTRAINT_CHECK
5820: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5830: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c  CONSTRAINT | (1<
5840: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5850: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5860: 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c  OMMITHOOK   (SQL
5870: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5880: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5890: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
58a0: 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20  NT_FOREIGNKEY   
58b0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
58c0: 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  NT | (3<<8)).#de
58d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
58e0: 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20  TRAINT_FUNCTION 
58f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5900: 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29  TRAINT | (4<<8))
5910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5920: 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55  CONSTRAINT_NOTNU
5930: 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  LL      (SQLITE_
5940: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c  CONSTRAINT | (5<
5950: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5960: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50  ITE_CONSTRAINT_P
5970: 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c  RIMARYKEY   (SQL
5980: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5990: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
59a0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
59b0: 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  NT_TRIGGER      
59c0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59d0: 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  NT | (7<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
59f0: 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20  TRAINT_UNIQUE   
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5a10: 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29  TRAINT | (8<<8))
5a20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a30: 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20  CONSTRAINT_VTAB 
5a40: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5a50: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c  CONSTRAINT | (9<
5a60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52  ITE_CONSTRAINT_R
5a80: 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c  OWID        (SQL
5a90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5aa0: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
5ab0: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5ac0: 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20  ECOVER_WAL      
5ad0: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5ae0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5af0: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5b00: 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20  ECOVER_ROLLBACK 
5b10: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5b20: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5b30: 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f   SQLITE_WARNING_
5b40: 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20  AUTOINDEX       
5b50: 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20  (SQLITE_WARNING 
5b60: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5b70: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53  e SQLITE_AUTH_US
5b80: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ER              
5b90: 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20   (SQLITE_AUTH | 
5ba0: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5bb0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
5bc0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
5bd0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
5be0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
5bf0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
5c00: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
5c10: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5c20: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5c30: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5c40: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5c50: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5c60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
5c70: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
5c80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c90: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
5ca0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5cb0: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
5cc0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5cd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ce0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
5cf0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5d00: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
5d10: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d30: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
5d40: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5d50: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
5d60: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d80: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
5d90: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
5da0: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
5db0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5dc0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
5dd0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5de0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
5df0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e00: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
5e10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5e20: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
5e30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e40: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
5e50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5e60: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
5e70: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5e80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e90: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
5ea0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5eb0: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
5ec0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5ed0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ee0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
5ef0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5f00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5f20: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
5f30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
5f40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5f60: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
5f70: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
5f80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5fa0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
5fb0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
5fc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5fd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5fe0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
5ff0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
6000: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6010: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6020: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
6030: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
6040: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6060: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
6070: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
6080: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6090: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
60a0: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
60b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
60c0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
60d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
60e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
60f0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
6100: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
6110: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6120: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6130: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6140: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6150: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
6160: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6170: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6180: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6190: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
61a0: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
61b0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
61c0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
61d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
61e0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
61f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
6200: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6210: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6220: 45 5f 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54 45  E_OPEN_FILEPROTE
6230: 43 54 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20 20  CTION_MASK      
6240: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6250: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 37             0x007
6260: 30 30 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72 76  00000../* Reserv
6270: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
6280: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6290: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
62a0: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
62b0: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
62c0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
62d0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
62e0: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
62f0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6300: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
6310: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
6320: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
6330: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ctor of these.**
6340: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
6350: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
6360: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
6370: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
6380: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
6390: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
63a0: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
63b0: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
63c0: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
63d0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
63e0: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
63f0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
6400: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
6410: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
6420: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6430: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
6440: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
6450: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
6460: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
6470: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
6480: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
6490: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
64a0: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
64b0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
64c0: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
64d0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
64e0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
64f0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
6500: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
6510: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
6520: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
6530: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
6540: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
6550: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
6560: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
6570: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
6580: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
6590: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
65a0: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
65b0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
65c0: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
65d0: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
65e0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
65f0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
6600: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
6610: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6620: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
6630: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6640: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
6650: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
6660: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
6670: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
6680: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
6690: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
66a0: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
66b0: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
66c0: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
66d0: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
66e0: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
66f0: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
6700: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
6710: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
6720: 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
6730: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6740: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6750: 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69  PEN.** flag indi
6760: 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c 65  cate that a file
6770: 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74   cannot be delet
6780: 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54  ed when open.  T
6790: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43  he.** SQLITE_IOC
67a0: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61  AP_IMMUTABLE fla
67b0: 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  g indicates that
67c0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a   the file is on.
67d0: 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64  ** read-only med
67e0: 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65  ia and cannot be
67f0: 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79   changed even by
6800: 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a   processes with.
6810: 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76  ** elevated priv
6820: 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69  ileges..*/.#defi
6830: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6840: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
6850: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6860: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6870: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6890: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
68a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
68b0: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20  OMIC1K          
68c0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
68d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
68e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
68f0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6900: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
6910: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6920: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC4K            
6930: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
6940: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6950: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
6960: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6970: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
6980: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6990: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  16K             
69a0: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
69b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
69c0: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
69d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
69e0: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
69f0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6a00: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6a10: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
6a20: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6a30: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20  AFE_APPEND      
6a40: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a60: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6a70: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a80: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
6a90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
6aa0: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
6ab0: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23  EN  0x00000800.#
6ac0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ad0: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6ae0: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30  ERWRITE    0x000
6af0: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
6b00: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6b10: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  ABLE            
6b20: 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a    0x00002000../*
6b30: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
6b40: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
6b50: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  s.**.** SQLite u
6b60: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
6b70: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6b80: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
6b90: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6ba0: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
6bb0: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
6bc0: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
6bd0: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
6be0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6bf0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
6c00: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
6c10: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
6c20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6c30: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
6c40: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6c50: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
6c60: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6c70: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6c80: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6c90: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
6ca0: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
6cb0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
6cc0: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
6cd0: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
6ce0: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
6cf0: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
6d00: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
6d10: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6d20: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
6d30: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
6d40: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
6d50: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6d60: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
6d70: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
6d80: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
6d90: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
6da0: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
6db0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
6dc0: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
6dd0: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
6de0: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
6df0: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
6e00: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
6e10: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
6e20: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
6e30: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c  r bits of the fl
6e40: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49  ag.** equal SQLI
6e50: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
6e60: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73  that means to us
6e70: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6e80: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49   semantics..** I
6e90: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6ea0: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49   bits equal SQLI
6eb0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68  TE_SYNC_FULL, th
6ec0: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  at means.** to u
6ed0: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c  se Mac OS X styl
6ee0: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65  e fullsync inste
6ef0: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a  ad of fsync()..*
6f00: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66  *.** Do not conf
6f10: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53  use the SQLITE_S
6f20: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6f30: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6f40: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68  flags.** with th
6f50: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  e [PRAGMA synchr
6f60: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e  onous]=NORMAL an
6f70: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  d [PRAGMA synchr
6f80: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73  onous]=FULL.** s
6f90: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73  ettings.  The [s
6fa0: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d  ynchronous pragm
6fb0: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  a] determines wh
6fc0: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  en calls to the.
6fd0: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74  ** xSync VFS met
6fe0: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70  hod occur and ap
6ff0: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20  plies uniformly 
7000: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66  across all platf
7010: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  orms..** The SQL
7020: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7030: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7040: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72  FULL flags deter
7050: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72  mine how.** ener
7060: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75  getic or rigorou
7070: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68  s or forceful th
7080: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  e sync operation
7090: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c  s are and.** onl
70a0: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65  y make a differe
70b0: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66  nce on Mac OSX f
70c0: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53  or the default S
70d0: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28  QLite code..** (
70e0: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20  Third-party VFS 
70f0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7100: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20  might also make 
7110: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  the distinction.
7120: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
7130: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7140: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7150: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68  LL, but among th
7160: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73  e.** operating s
7170: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20  ystems natively 
7180: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
7190: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53  ite, only Mac OS
71a0: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74  X.** cares about
71b0: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e   the difference.
71c0: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ).*/.#define SQL
71d0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
71e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
71f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7200: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
7210: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
7220: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
7230: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
7240: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
7250: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7260: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
7270: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
7280: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7290: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
72a0: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
72b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
72c0: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20   | OS interface 
72d0: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64  layer].  Individ
72e0: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
72f0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
7300: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
7310: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
7320: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
7330: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
7340: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
7350: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
7360: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
7370: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
7380: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
7390: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
73a0: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
73b0: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
73c0: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
73d0: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
73e0: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
73f0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7400: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
7410: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
7420: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
7430: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
7440: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7450: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
7460: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
7470: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
7480: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7490: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
74a0: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
74b0: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45  s Object.**.** E
74c0: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
74d0: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
74e0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
74f0: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
7500: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7510: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
7520: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
7530: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
7540: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7550: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
7560: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
7570: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
7580: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
7590: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
75a0: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
75b0: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
75c0: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
75d0: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
75e0: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
75f0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7600: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
7610: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71  **.** If the [sq
7620: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7630: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
7640: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7650: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
7660: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
7670: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
7680: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
7690: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
76a0: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
76b0: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
76c0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
76d0: 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74  Open] reported t
76e0: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20  hat it failed.  
76f0: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20  The.** only way 
7700: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c  to prevent a cal
7710: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c  l to xClose foll
7720: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b  owing a failed [
7730: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7740: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  n].** is for the
7750: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7760: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20  pen] to set the 
7770: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
7780: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a  thods element.**
7790: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
77a0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
77b0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
77c0: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
77d0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
77e0: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
77f0: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
7800: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
7810: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
7820: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
7830: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
7840: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
7850: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
7860: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
7870: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
7880: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
7890: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
78a0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
78b0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
78c0: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
78d0: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
78e0: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
78f0: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
7900: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
7910: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
7920: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7930: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
7940: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7950: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
7960: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7970: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
7980: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7990: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
79a0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
79b0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
79c0: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
79d0: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
79e0: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
79f0: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
7a00: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
7a10: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
7a20: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
7a30: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
7a40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
7a50: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
7a60: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
7a70: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
7a80: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
7a90: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
7aa0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
7ab0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
7ac0: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
7ad0: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
7ae0: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
7af0: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
7b00: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
7b10: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
7b20: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
7b30: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
7b40: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
7b50: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7b60: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
7b70: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
7b80: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
7b90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7ba0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
7bb0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
7bc0: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
7bd0: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
7be0: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
7bf0: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
7c00: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
7c10: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
7c20: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
7c30: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
7c40: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
7c50: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
7c60: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
7c70: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
7c80: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
7c90: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
7ca0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
7cb0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
7cc0: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
7cd0: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
7ce0: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
7cf0: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
7d00: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
7d10: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
7d20: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
7d30: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
7d40: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
7d50: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
7d60: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
7d70: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
7d80: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
7d90: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
7da0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
7db0: 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e  ..** A [file con
7dc0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c  trol opcodes | l
7dd0: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
7de0: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
7df0: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
7e00: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
7e10: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
7e20: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7e30: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
7e40: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74  opcodes.** great
7e50: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
7e60: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20  void conflicts. 
7e70: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7e80: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  ions should.** r
7e90: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
7ea0: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65  TFOUND] for file
7eb0: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
7ec0: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
7ed0: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a  t.** recognize..
7ee0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
7ef0: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
7f00: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
7f10: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
7f20: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
7f30: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
7f40: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
7f50: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
7f60: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
7f70: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
7f80: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
7f90: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
7fa0: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
7fb0: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
7fc0: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
7fd0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
7fe0: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
7ff0: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
8000: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
8010: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
8020: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8030: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8040: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
8050: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8060: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
8070: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8080: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
8090: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
80a0: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
80b0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
80c0: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
80d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
80e0: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
80f0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8100: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
8110: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8120: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
8130: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8140: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
8150: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8160: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
8170: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8180: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
8190: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
81a0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
81b0: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
81c0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
81d0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
81e0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
81f0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8200: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
8210: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
8220: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
8230: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
8240: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
8250: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
8260: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
8270: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
8280: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
8290: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
82a0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
82b0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
82c0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
82d0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
82e0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
82f0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
8300: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
8310: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
8320: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
8330: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
8340: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
8350: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
8360: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
8370: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
8380: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
8390: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
83a0: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
83b0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
83c0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
83d0: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78  te()..**.** If x
83e0: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53  Read() returns S
83f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
8400: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61  T_READ it must a
8410: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74  lso fill.** in t
8420: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f  he unread portio
8430: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ns of the buffer
8440: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
8450: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c  VFS that.** fail
8460: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  s to zero-fill s
8470: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74  hort reads might
8480: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20   seem to work.  
8490: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c  However,.** fail
84a0: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ure to zero-fill
84b0: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c   short reads wil
84c0: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61  l eventually lea
84d0: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65  d to.** database
84e0: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
84f0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
8500: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8510: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
8520: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
8530: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8540: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
8550: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
8560: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8570: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
8580: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8590: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
85a0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
85b0: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
85c0: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
85d0: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
85e0: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
85f0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
8600: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
8610: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
8620: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8630: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
8640: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
8650: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
8660: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
8670: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
8680: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8690: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
86a0: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
86b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
86c0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
86d0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
86e0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
86f0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
8700: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8710: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
8720: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f  .  int (*xFileCo
8730: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66  ntrol)(sqlite3_f
8740: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  ile*, int op, vo
8750: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74  id *pArg);.  int
8760: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28   (*xSectorSize)(
8770: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8780: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43    int (*xDeviceC
8790: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28  haracteristics)(
87a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
87b0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
87c0: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
87d0: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20   version 1 */.  
87e0: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73  int (*xShmMap)(s
87f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8800: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c  t iPg, int pgsz,
8810: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74   int, void volat
8820: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  ile**);.  int (*
8830: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65  xShmLock)(sqlite
8840: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66  3_file*, int off
8850: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20  set, int n, int 
8860: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28  flags);.  void (
8870: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71  *xShmBarrier)(sq
8880: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8890: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29  int (*xShmUnmap)
88a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88b0: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
88c0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
88d0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
88e0: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20  r version 2 */. 
88f0: 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73   int (*xFetch)(s
8900: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8910: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8920: 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69  t, int iAmt, voi
8930: 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28  d **pp);.  int (
8940: 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74  *xUnfetch)(sqlit
8950: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8960: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76  3_int64 iOfst, v
8970: 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65  oid *p);.  /* Me
8980: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8990: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
89a0: 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69  n 3 */.  /* Addi
89b0: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
89c0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
89d0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
89e0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
89f0: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
8a00: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
8a10: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
8a20: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
8a30: 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f  pcodes} {file co
8a40: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a  ntrol opcode}.**
8a50: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
8a60: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
8a70: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
8a80: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8a90: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
8aa0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8ab0: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
8ac0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
8ad0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
8ae0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
8af0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8b00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
8b10: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
8b20: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
8b30: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
8b40: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
8b50: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
8b60: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
8b70: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
8b80: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
8b90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
8ba0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8bb0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
8bc0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8bd0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
8be0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
8bf0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
8c00: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
8c10: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
8c20: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
8c30: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
8c40: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
8c50: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
8c60: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
8c70: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
8c80: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
8c90: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
8ca0: 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  ned..** <ul>.** 
8cb0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8cc0: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a  TL_SIZE_HINT]].*
8cd0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8ce0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f  NTL_SIZE_HINT] o
8cf0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79  pcode is used by
8d00: 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20   SQLite to give 
8d10: 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72  the VFS.** layer
8d20: 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c   a hint of how l
8d30: 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73  arge the databas
8d40: 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77  e file will grow
8d50: 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68   to be during th
8d60: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61  e.** current tra
8d70: 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nsaction.  This 
8d80: 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72  hint is not guar
8d90: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63  anteed to be acc
8da0: 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20  urate but it.** 
8db0: 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20  is often close. 
8dc0: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   The underlying 
8dd0: 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65  VFS might choose
8de0: 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20   to preallocate 
8df0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
8e00: 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20   space based on 
8e10: 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64  this hint in ord
8e20: 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65  er to help write
8e30: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
8e40: 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61  e.** file run fa
8e50: 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ster..**.** <li>
8e60: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
8e70: 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  HUNK_SIZE]].** T
8e80: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8e90: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63  _CHUNK_SIZE] opc
8ea0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ode is used to r
8eb0: 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20  equest that the 
8ec0: 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61  VFS.** extends a
8ed0: 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65  nd truncates the
8ee0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
8ef0: 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69  n chunks of a si
8f00: 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ze specified.** 
8f10: 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65  by the user. The
8f20: 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
8f30: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   to [sqlite3_fil
8f40: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f  e_control()] sho
8f50: 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  uld .** point to
8f60: 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70   an integer (typ
8f70: 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e  e int) containin
8f80: 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d  g the new chunk-
8f90: 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66  size to use.** f
8fa0: 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64  or the nominated
8fb0: 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63   database. Alloc
8fc0: 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66  ating database f
8fd0: 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72  ile space in lar
8fe0: 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61  ge.** chunks (sa
8ff0: 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29  y 1MB at a time)
9000: 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c  , may reduce fil
9010: 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e  e-system fragmen
9020: 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d  tation and.** im
9030: 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
9040: 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d  e on some system
9050: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
9060: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
9070: 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68  _POINTER]].** Th
9080: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9090: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  FILE_POINTER] op
90a0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
90b0: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72  obtain a pointer
90c0: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
90d0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
90e0: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
90f0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
9100: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
9110: 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b  tion.  See the [
9120: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9130: 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74  trol()] document
9140: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64  ation for.** add
9150: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
9160: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
9170: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9180: 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20  NC_OMITTED]].** 
9190: 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65  No longer in use
91a0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
91b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d  LITE_FCNTL_SYNC]
91c0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
91d0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63  _FCNTL_SYNC] opc
91e0: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
91f0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
9200: 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e  QLite and.** sen
9210: 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d  t to the VFS imm
9220: 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20  ediately before 
9230: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9240: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61   is invoked on a
9250: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c  .** database fil
9260: 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72  e descriptor. Or
9270: 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d  , if the xSync m
9280: 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76  ethod is not inv
9290: 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65  oked .** because
92a0: 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63 6f   the user has co
92b0: 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65 20  nfigured SQLite 
92c0: 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  with .** [PRAGMA
92d0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50   synchronous | P
92e0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
92f0: 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76  s=OFF] it is inv
9300: 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a  oked in place .*
9310: 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d  * of the xSync m
9320: 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63  ethod. In most c
9330: 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65  ases, the pointe
9340: 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  r argument passe
9350: 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66  d with.** this f
9360: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e  ile-control is N
9370: 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66  ULL. However, if
9380: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9390: 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63  le is being sync
93a0: 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ed.** as part of
93b0: 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73   a multi-databas
93c0: 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72  e commit, the ar
93d0: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
93e0: 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
93f0: 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  d.** string cont
9400: 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73  aining the trans
9410: 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a  actions master-j
9420: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65  ournal file name
9430: 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a  . VFSes that .**
9440: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
9450: 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20  s signal should 
9460: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
9470: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70  this opcode. App
9480: 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68  lications .** sh
9490: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73  ould not call [s
94a0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
94b0: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73  rol()] with this
94c0: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
94d0: 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72   so may .** disr
94e0: 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f  upt the operatio
94f0: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
9500: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20  ized VFSes that 
9510: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
9520: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9530: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
9540: 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54  _PHASETWO]].** T
9550: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9560: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
9570: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
9580: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
9590: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
95a0: 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  d sent to the VF
95b0: 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73 61  S after a transa
95c0: 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63  ction has been c
95d0: 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61  ommitted immedia
95e0: 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f  tely.** but befo
95f0: 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  re the database 
9600: 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53  is unlocked. VFS
9610: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e  es that do not n
9620: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a  eed this signal.
9630: 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  ** should silent
9640: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
9650: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
9660: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
9670: 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
9680: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9690: 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65  with this opcode
96a0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
96b0: 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a   disrupt the .**
96c0: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
96d0: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
96e0: 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75  Ses that do requ
96f0: 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20  ire it.  .**.** 
9700: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9710: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
9720: 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  Y]].** ^The [SQL
9730: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
9740: 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65  AV_RETRY] opcode
9750: 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66   is used to conf
9760: 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a  igure automatic.
9770: 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20  ** retry counts 
9780: 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f  and intervals fo
9790: 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49  r certain disk I
97a0: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f  /O operations fo
97b0: 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73  r the.** windows
97c0: 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20   [VFS] in order 
97d0: 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73  to provide robus
97e0: 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65  tness in the pre
97f0: 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69  sence of.** anti
9800: 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e  -virus programs.
9810: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
9820: 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69  e windows VFS wi
9830: 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65  ll retry file re
9840: 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74  ad,.** file writ
9850: 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65  e, and file dele
9860: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70  te operations up
9870: 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69   to 10 times, wi
9880: 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66  th a delay.** of
9890: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
98a0: 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73   before the firs
98b0: 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68  t retry and with
98c0: 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65   the delay incre
98d0: 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61  asing.** by an a
98e0: 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c  dditional 25 mil
98f0: 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65  liseconds with e
9900: 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72  ach subsequent r
9910: 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  etry.  This.** o
9920: 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65  pcode allows the
9930: 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31  se two values (1
9940: 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35  0 retries and 25
9950: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
9960: 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65   delay).** to be
9970: 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20   adjusted.  The 
9980: 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67  values are chang
9990: 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62  ed for all datab
99a0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
99b0: 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  ** within the sa
99c0: 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65  me process.  The
99d0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
99e0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72  ointer to an arr
99f0: 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74  ay of two.** int
9a00: 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20  egers where the 
9a10: 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20  first integer i 
9a20: 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f  the new retry co
9a30: 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  unt and the seco
9a40: 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73  nd.** integer is
9a50: 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20   the delay.  If 
9a60: 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69  either integer i
9a70: 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
9a80: 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20   the setting.** 
9a90: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62  is not changed b
9aa0: 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70  ut instead the p
9ab0: 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
9ac0: 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72  at setting is wr
9ad0: 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68  itten.** into th
9ae0: 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61  e array entry, a
9af0: 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72  llowing the curr
9b00: 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e  ent retry settin
9b10: 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65  gs to be.** inte
9b20: 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a  rrogated.  The z
9b30: 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  DbName parameter
9b40: 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
9b50: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9b60: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
9b70: 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  L]].** ^The [SQL
9b80: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
9b90: 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73  T_WAL] opcode is
9ba0: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
9bb0: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
9bc0: 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57  sistent [WAL | W
9bd0: 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20  rite Ahead Log] 
9be0: 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66  setting.  By def
9bf0: 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69  ault, the auxili
9c00: 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65  ary.** write ahe
9c10: 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65  ad log and share
9c20: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75  d memory files u
9c30: 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74  sed for transact
9c40: 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61  ion control.** a
9c50: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
9c60: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68   deleted when th
9c70: 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74  e latest connect
9c80: 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62  ion to the datab
9c90: 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20  ase.** closes.  
9ca0: 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65  Setting persiste
9cb0: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73  nt WAL mode caus
9cc0: 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74  es those files t
9cd0: 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a  o persist after.
9ce0: 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69  ** close.  Persi
9cf0: 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20  sting the files 
9d00: 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f  is useful when o
9d10: 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74  ther processes t
9d20: 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61  hat do not.** ha
9d30: 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73  ve write permiss
9d40: 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63  ion on the direc
9d50: 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  tory containing 
9d60: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9d70: 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61  e want.** to rea
9d80: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  d the database f
9d90: 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20  ile, as the WAL 
9da0: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
9db0: 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69  y files must exi
9dc0: 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66  st.** in order f
9dd0: 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
9de0: 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20  to be readable. 
9df0: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
9e00: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
9e10: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9e20: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
9e30: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
9e40: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
9e50: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
9e60: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
9e70: 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65  disable persiste
9e80: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31  nt WAL mode or 1
9e90: 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69   to enable persi
9ea0: 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64  stent.** WAL mod
9eb0: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67  e.  If the integ
9ec0: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69  er is -1, then i
9ed0: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  t is overwritten
9ee0: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
9ef0: 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74  t.** WAL persist
9f00: 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  ence setting..**
9f10: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9f20: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
9f30: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
9f40: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9f50: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
9f60: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
9f70: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
9f80: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
9f90: 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73  rsistent "powers
9fa0: 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f  afe-overwrite" o
9fb0: 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67  r "PSOW" setting
9fc0: 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74  .  The PSOW sett
9fd0: 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65  ing.** determine
9fe0: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f  s the [SQLITE_IO
9ff0: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
a000: 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20  ERWRITE] bit of 
a010: 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68  the.** xDeviceCh
a020: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
a030: 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74  thods. The fourt
a040: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
a050: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
a060: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
a070: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
a080: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
a090: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
a0a0: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
a0b0: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65   0 to disable ze
a0c0: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f  ro-damage mode o
a0d0: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65  r 1 to enable ze
a0e0: 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64  ro-damage.** mod
a0f0: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67  e.  If the integ
a100: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69  er is -1, then i
a110: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  t is overwritten
a120: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
a130: 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65  t.** zero-damage
a140: 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a   mode setting..*
a150: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a160: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
a170: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a180: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a190: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  ITE] opcode is i
a1a0: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
a1b0: 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a   after opening.*
a1c0: 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61  * a write transa
a1d0: 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74  ction to indicat
a1e0: 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69  e that, unless i
a1f0: 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t is rolled back
a200: 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61   for some.** rea
a210: 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20  son, the entire 
a220: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
a230: 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ll be overwritte
a240: 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74  n by the current
a250: 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e   .** transaction
a260: 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62  . This is used b
a270: 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69  y VACUUM operati
a280: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ons..**.** <li>[
a290: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a2a0: 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  SNAME]].** ^The 
a2b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a2c0: 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61  SNAME] opcode ca
a2d0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
a2e0: 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
a2f0: 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20  .** all [VFSes] 
a300: 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b  in the VFS stack
a310: 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65  .  The names are
a320: 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d   of all VFS shim
a330: 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e  s and the.** fin
a340: 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20  al bottom-level 
a350: 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20  VFS are written 
a360: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
a370: 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
a380: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
a390: 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20   and the result 
a3a0: 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  is stored in the
a3b0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a   char* variable.
a3c0: 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72  ** that the four
a3d0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
a3e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a3f0: 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20  ntrol()] points 
a400: 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65  to..** The calle
a410: 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  r is responsible
a420: 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65   for freeing the
a430: 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e   memory when don
a440: 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61  e.  As with.** a
a450: 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ll file-control 
a460: 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69  actions, there i
a470: 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74  s no guarantee t
a480: 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63  hat this will ac
a490: 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79  tually.** do any
a4a0: 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20  thing.  Callers 
a4b0: 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a  should initializ
a4c0: 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  e the char* vari
a4d0: 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a  able to a NULL.*
a4e0: 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73  * pointer in cas
a4f0: 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  e this file-cont
a500: 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  rol is not imple
a510: 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69  mented.  This fi
a520: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73  le-control.** is
a530: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69   intended for di
a540: 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c  agnostic use onl
a550: 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  y..**.** <li>[[S
a560: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a570: 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65  MA]].** ^Wheneve
a580: 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  r a [PRAGMA] sta
a590: 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64  tement is parsed
a5a0: 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e  , an [SQLITE_FCN
a5b0: 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66  TL_PRAGMA] .** f
a5c0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73  ile control is s
a5d0: 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20  ent to the open 
a5e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
a5f0: 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64  bject correspond
a600: 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61  ing.** to the da
a610: 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77  tabase file to w
a620: 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20  hich the pragma 
a630: 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73  statement refers
a640: 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a  . ^The argument.
a650: 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54  ** to the [SQLIT
a660: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a670: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
a680: 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70  an array of.** p
a690: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
a6a0: 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77  gs (char**) in w
a6b0: 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20  hich the second 
a6c0: 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  element of the a
a6d0: 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e  rray.** is the n
a6e0: 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ame of the pragm
a6f0: 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20  a and the third 
a700: 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61  element is the a
a710: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a  rgument to the.*
a720: 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c  * pragma or NULL
a730: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68   if the pragma h
a740: 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20  as no argument. 
a750: 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f   ^The handler fo
a760: 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r an.** [SQLITE_
a770: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
a780: 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f  le control can o
a790: 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74  ptionally make t
a7a0: 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74  he first element
a7b0: 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a  .** of the char*
a7c0: 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  * argument point
a7d0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74   to a string obt
a7e0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
a7f0: 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a  te3_mprintf()].*
a800: 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c  * or the equival
a810: 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72  ent and that str
a820: 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20  ing will become 
a830: 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68  the result of th
a840: 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74  e pragma or.** t
a850: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
a860: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66   if the pragma f
a870: 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a  ails. ^If the.**
a880: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a890: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
a8a0: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
a8b0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
a8c0: 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b  hen normal .** [
a8d0: 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69  PRAGMA] processi
a8e0: 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e  ng continues.  ^
a8f0: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
a900: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
a910: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
a920: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
a930: 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65  , then the parse
a940: 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  r assumes that t
a950: 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61  he.** VFS has ha
a960: 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41  ndled the PRAGMA
a970: 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20   itself and the 
a980: 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73  parser generates
a990: 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70   a no-op.** prep
a9a0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20  ared statement. 
a9b0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a9c0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
a9d0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
a9e0: 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c  rns.** any resul
a9f0: 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61  t code other tha
aa00: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  n [SQLITE_OK] or
aa10: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
aa20: 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  D], that means.*
aa30: 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65  * that the VFS e
aa40: 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72  ncountered an er
aa50: 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69  ror while handli
aa60: 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20  ng the [PRAGMA] 
aa70: 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  and the.** compi
aa80: 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52  lation of the PR
aa90: 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20  AGMA fails with 
aaa0: 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20  an error.  ^The 
aab0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
aac0: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
aad0: 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20  ntrol occurs at 
aae0: 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
aaf0: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
ab00: 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73  t analysis and s
ab10: 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20  o.** it is able 
ab20: 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c  to override buil
ab30: 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74  t-in [PRAGMA] st
ab40: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
ab50: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ab60: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d  TL_BUSYHANDLER]]
ab70: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
ab80: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
ab90: 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  ER].** file-cont
aba0: 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  rol may be invok
abb0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20  ed by SQLite on 
abc0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
abd0: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72  e handle.** shor
abe0: 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20  tly after it is 
abf0: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20  opened in order 
ac00: 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73  to provide a cus
ac10: 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63  tom VFS with acc
ac20: 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  ess.** to the co
ac30: 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68  nnections busy-h
ac40: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  andler callback.
ac50: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
ac60: 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a   of type (void *
ac70: 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79  *).** - an array
ac80: 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29   of two (void *)
ac90: 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72   values. The fir
aca0: 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75  st (void *) actu
acb0: 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74  ally points.** t
acc0: 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
acd0: 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f  type (int (*)(vo
ace0: 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72  id *)). In order
acf0: 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63   to invoke the c
ad00: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75  onnections.** bu
ad10: 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73  sy-handler, this
ad20: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
ad30: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
ad40: 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69   the second (voi
ad50: 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61  d *) in.** the a
ad60: 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79  rray as the only
ad70: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74   argument. If it
ad80: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
ad90: 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72  o, then the oper
ada0: 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
adb0: 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69  be retried. If i
adc0: 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  t returns zero, 
add0: 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73  the custom VFS s
ade0: 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68  hould abandon th
adf0: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65  e.** current ope
ae00: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ration..**.** <l
ae10: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ae20: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a  _TEMPFILENAME]].
ae30: 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20  ** ^Application 
ae40: 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b  can invoke the [
ae50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
ae60: 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d  PFILENAME] file-
ae70: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61  control.** to ha
ae80: 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61  ve SQLite genera
ae90: 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  te a.** temporar
aea0: 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67  y filename using
aeb0: 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
aec0: 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c  thm that is foll
aed0: 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65  owed to generate
aee0: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
aef0: 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50  lenames for TEMP
af00: 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65   tables and othe
af10: 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e  r internal uses.
af20: 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e    The.** argumen
af30: 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68  t should be a ch
af40: 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  ar** which will 
af50: 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  be filled with t
af60: 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
af70: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
af80: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
af90: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
afa0: 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72  ()].  The caller
afb0: 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b   should.** invok
afc0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
afd0: 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74  )] on the result
afe0: 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f   to avoid a memo
aff0: 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c  ry leak..**.** <
b000: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b010: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  L_MMAP_SIZE]].**
b020: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b030: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
b040: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
b050: 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73  ed to query or s
b060: 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75  et the.** maximu
b070: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b080: 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75  s that will be u
b090: 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d  sed for memory-m
b0a0: 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68  apped I/O..** Th
b0b0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
b0c0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
b0d0: 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74  ue of type sqlit
b0e0: 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a  e3_int64 that.**
b0f0: 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20   is an advisory 
b100: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
b110: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  f bytes in the f
b120: 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61  ile to memory ma
b130: 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74  p.  The.** point
b140: 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  er is overwritte
b150: 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76  n with the old v
b160: 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74  alue.  The limit
b170: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
b180: 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  if.** the value 
b190: 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74  originally point
b1a0: 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76  ed to is negativ
b1b0: 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75  e, and so the cu
b1c0: 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20  rrent limit .** 
b1d0: 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62  can be queried b
b1e0: 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70  y passing in a p
b1f0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61  ointer to a nega
b200: 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68  tive number.  Th
b210: 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  is.** file-contr
b220: 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  ol is used inter
b230: 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65  nally to impleme
b240: 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  nt [PRAGMA mmap_
b250: 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  size]..**.** <li
b260: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b270: 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  TRACE]].** The [
b280: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b290: 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  CE] file control
b2a0: 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f   provides adviso
b2b0: 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ry information.*
b2c0: 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f  * to the VFS abo
b2d0: 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68  ut what the high
b2e0: 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65  er layers of the
b2f0: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72   SQLite stack ar
b300: 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73  e doing..** This
b310: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b320: 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46   used by some VF
b330: 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69  S activity traci
b340: 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54  ng [shims]..** T
b350: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
b360: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
b370: 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72   string.  Higher
b380: 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a   layers in the.*
b390: 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d  * SQLite stack m
b3a0: 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74  ay generate inst
b3b0: 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69  ances of this fi
b3c0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a  le control if.**
b3d0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
b3e0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f  _FCNTL_TRACE] co
b3f0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
b400: 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
b410: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b420: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
b430: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b440: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
b450: 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  D] file control 
b460: 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61  interprets its a
b470: 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20  rgument as a.** 
b480: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
b490: 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69  teger and it wri
b4a0: 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e  tes a boolean in
b4b0: 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
b4c0: 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20  depending.** on 
b4d0: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
b4e0: 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e  he file has been
b4f0: 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c   renamed, moved,
b500: 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63   or deleted sinc
b510: 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73  e it.** was firs
b520: 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  t opened..**.** 
b530: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b540: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
b550: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  DLE]].** The [SQ
b560: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
b570: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63  _SET_HANDLE] opc
b580: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
b590: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
b5a0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
b5b0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
b5c0: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61  ol method to swa
b5d0: 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c  p the file handl
b5e0: 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a  e with the one.*
b5f0: 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
b600: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
b610: 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c  t.  This capabil
b620: 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69  ity is used duri
b630: 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e  ng testing.** an
b640: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
b650: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
b660: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73  n SQLITE_TEST is
b670: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
b680: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
b690: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
b6a0: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
b6b0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
b6c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
b6d0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
b6e0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
b6f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
b700: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
b710: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
b720: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
b730: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
b740: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
b750: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
b760: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
b770: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
b780: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
b790: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
b7a0: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
b7b0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
b7c0: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
b7d0: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
b7e0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
b7f0: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
b800: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b810: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
b820: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
b830: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b840: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
b850: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
b860: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b870: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
b880: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
b890: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b8a0: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
b8b0: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
b8c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b8d0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
b8e0: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
b8f0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b900: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
b910: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
b920: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b930: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
b940: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
b950: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
b960: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
b970: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
b980: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
b990: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
b9a0: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
b9b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b9c0: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
b9d0: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
b9e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
b9f0: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
ba00: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
ba10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
ba20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
ba30: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
ba40: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
ba50: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
ba60: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
ba70: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
ba80: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
ba90: 32 33 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64  23./* deprecated
baa0: 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e   names */.#defin
bab0: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
bac0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
bad0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
bae0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23  _LOCKPROXYFILE.#
baf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
bb00: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
bb10: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
bb20: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
bb30: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  ILE.#define SQLI
bb40: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
bb50: 20 20 20 20 20 20 20 20 20 20 53 51 4c 49 54 45            SQLITE
bb60: 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e  _FCNTL_LAST_ERRN
bb70: 4f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  O../*.** CAPI3RE
bb80: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
bb90: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
bba0: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
bbb0: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
bbc0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
bbd0: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
bbe0: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
bbf0: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
bc00: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
bc10: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
bc20: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
bc30: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
bc40: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
bc50: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
bc60: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
bc70: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
bc80: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
bc90: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
bca0: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
bcb0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
bcc0: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
bcd0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
bce0: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
bcf0: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
bd00: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
bd10: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
bd20: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
bd30: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
bd40: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
bd50: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
bd60: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
bd70: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
bd80: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
bd90: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
bda0: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
bdb0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
bdc0: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
bdd0: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
bde0: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a  system".  See.**
bdf0: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20   the [VFS | VFS 
be00: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
be10: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72  or further infor
be20: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
be30: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
be40: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
be50: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
be60: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
be70: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
be80: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
be90: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
bea0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
beb0: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
bec0: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
bed0: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
bee0: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
bef0: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
bf00: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
bf10: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
bf20: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
bf30: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
bf40: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
bf50: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
bf60: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
bf70: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
bf80: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
bf90: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
bfa0: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
bfb0: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
bfc0: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
bfd0: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
bfe0: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
bff0: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
c000: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
c010: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
c020: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
c030: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
c040: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
c050: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
c060: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
c070: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
c080: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
c090: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
c0a0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
c0b0: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
c0c0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
c0d0: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
c0e0: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
c0f0: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
c100: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
c110: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
c120: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
c130: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
c140: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
c150: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
c160: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
c170: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
c180: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
c190: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
c1a0: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
c1b0: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
c1c0: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
c1d0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
c1e0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
c1f0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
c200: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
c210: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
c220: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
c230: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
c240: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
c250: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
c260: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
c270: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
c280: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
c290: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
c2a0: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
c2b0: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
c2c0: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
c2d0: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
c2e0: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
c2f0: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
c300: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
c310: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
c320: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
c330: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
c340: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  les..**.** [[sql
c350: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d  ite3_vfs.xOpen]]
c360: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
c370: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
c380: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
c390: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
c3a0: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
c3b0: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
c3c0: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
c3d0: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
c3e0: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69  e() with an opti
c3f0: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65  onal suffix adde
c400: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66  d..** ^If a suff
c410: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74  ix is added to t
c420: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
c430: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a  ameter, it will.
c440: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20  ** consist of a 
c450: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61  single "-" chara
c460: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79  cter followed by
c470: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a   no more than.**
c480: 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   11 alphanumeric
c490: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72   and/or "-" char
c4a0: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69  acters..** ^SQLi
c4b0: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
c4c0: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
c4d0: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
c4e0: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
c4f0: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
c500: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
c510: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
c520: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
c530: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
c540: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
c550: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
c560: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
c570: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
c580: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
c590: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
c5a0: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
c5b0: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
c5c0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
c5d0: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
c5e0: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
c5f0: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
c600: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
c610: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
c620: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72  file.  ^Whenever
c630: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
c640: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
c650: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
c660: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
c670: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
c680: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
c690: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
c6a0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
c6b0: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
c6c0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
c6d0: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
c6e0: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
c6f0: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
c700: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
c710: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
c720: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
c730: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
c740: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
c750: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
c760: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
c770: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
c780: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
c790: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
c7a0: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
c7b0: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
c7c0: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
c7d0: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
c7e0: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
c7f0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
c800: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
c810: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
c820: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
c830: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  t..**.** ^(SQLit
c840: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
c850: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
c860: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
c870: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
c880: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
c890: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
c8a0: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
c8b0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
c8c0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
c8d0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
c8e0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
c8f0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
c900: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
c910: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
c920: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
c930: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
c940: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c950: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
c960: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c970: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
c980: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
c990: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
c9a0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
c9b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d  SQLITE_OPEN_WAL]
c9c0: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
c9d0: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
c9e0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
c9f0: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
ca00: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
ca10: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
ca20: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
ca30: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
ca40: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
ca50: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
ca60: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
ca70: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
ca80: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
ca90: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
caa0: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
cab0: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
cac0: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
cad0: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
cae0: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
caf0: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
cb00: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
cb10: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
cb20: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
cb30: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
cb40: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
cb50: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
cb60: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
cb70: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
cb80: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
cb90: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
cba0: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
cbb0: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
cbc0: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
cbd0: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
cbe0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
cbf0: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
cc00: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
cc10: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
cc20: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
cc30: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
cc40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
cc50: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
cc60: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
cc70: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
cc80: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
cc90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
cca0: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
ccb0: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
ccc0: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
ccd0: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
cce0: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c  osed.  ^The [SQL
ccf0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
cd00: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
cd10: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
cd20: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68  databases and th
cd30: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72  eir journals, tr
cd40: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62  ansient.** datab
cd50: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75  ases, and subjou
cd60: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rnals..**.** ^Th
cd70: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
cd80: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
cd90: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
cda0: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
cdb0: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
cdc0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
cdd0: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
cde0: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
cdf0: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
ce00: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
ce10: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
ce20: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
ce30: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
ce40: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
ce50: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
ce60: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
ce70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
ce80: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
ce90: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
cea0: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
ceb0: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
cec0: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
ced0: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
cee0: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
cef0: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
cf00: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
cf10: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
cf20: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
cf30: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
cf40: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c  ess..**.** ^At l
cf50: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
cf60: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
cf70: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
cf80: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
cf90: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
cfa0: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
cfb0: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
cfc0: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
cfd0: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
cfe0: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
cff0: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
d000: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
d010: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
d020: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
d030: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
d040: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
d050: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
d060: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
d070: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
d080: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
d090: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
d0a0: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
d0b0: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
d0c0: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
d0d0: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
d0e0: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
d0f0: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
d100: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
d110: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
d120: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
d130: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
d140: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
d150: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
d160: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
d170: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73   call..**.** [[s
d180: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65  qlite3_vfs.xAcce
d190: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ss]].** ^The fla
d1a0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
d1b0: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
d1c0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
d1d0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
d1e0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
d1f0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
d200: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
d210: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
d220: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
d230: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
d240: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
d250: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
d260: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
d270: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
d280: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
d290: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
d2a0: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
d2b0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
d2c0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
d2d0: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
d2e0: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
d2f0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
d300: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
d310: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
d320: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
d330: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
d340: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
d350: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
d360: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
d370: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
d380: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
d390: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
d3a0: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
d3b0: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
d3c0: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
d3d0: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
d3e0: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
d3f0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
d400: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
d410: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
d420: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
d430: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
d440: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
d450: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
d460: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
d470: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
d480: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
d490: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
d4a0: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
d4b0: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
d4c0: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
d4d0: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
d4e0: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
d4f0: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
d500: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
d510: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
d520: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
d530: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
d540: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
d550: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
d560: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
d570: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
d580: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
d590: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
d5a0: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
d5b0: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
d5c0: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
d5d0: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
d5e0: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
d5f0: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
d600: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
d610: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
d620: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
d630: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
d640: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
d650: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
d660: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
d670: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
d680: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
d690: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
d6a0: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
d6b0: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
d6c0: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
d6d0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
d6e0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
d6f0: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
d700: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
d710: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
d720: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30  lied by 86400000
d730: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
d740: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
d750: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
d760: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
d770: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
d780: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
d790: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
d7a0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
d7b0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
d7c0: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
d7d0: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
d7e0: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
d7f0: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
d800: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
d810: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
d820: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
d830: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
d840: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
d850: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
d860: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
d870: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
d880: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
d890: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
d8a0: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
d8b0: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
d8c0: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
d8d0: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
d8e0: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
d8f0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
d900: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
d910: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
d920: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
d930: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
d940: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
d950: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
d960: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
d970: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
d980: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
d990: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
d9a0: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
d9b0: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
d9c0: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
d9d0: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
d9e0: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
d9f0: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
da00: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
da10: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
da20: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
da30: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
da40: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
da50: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
da60: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
da70: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
da80: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
da90: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
daa0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
dab0: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
dac0: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
dad0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
dae0: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
daf0: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
db00: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
db10: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
db20: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
db30: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
db40: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
db50: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
db60: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
db70: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
db80: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
db90: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
dba0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
dbb0: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
dbc0: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
dbd0: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
dbe0: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
dbf0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
dc00: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
dc10: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
dc20: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
dc30: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
dc40: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
dc50: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
dc60: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
dc70: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
dc80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
dc90: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
dca0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
dcb0: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
dcc0: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
dcd0: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
dce0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
dcf0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
dd00: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
dd10: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
dd20: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
dd30: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
dd40: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
dd50: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
dd60: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
dd70: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
dd80: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
dd90: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
dda0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ddb0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
ddc0: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
ddd0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
dde0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
ddf0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
de00: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
de10: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
de20: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
de30: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
de40: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
de50: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
de60: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
de70: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
de80: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
de90: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
dea0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
deb0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
dec0: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
ded0: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
dee0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
def0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
df00: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
df10: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
df20: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
df30: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
df40: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
df50: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
df60: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
df70: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
df80: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
df90: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
dfa0: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
dfb0: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
dfc0: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
dfd0: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
dfe0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
dff0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
e000: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
e010: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
e020: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
e030: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
e040: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
e050: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
e060: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
e070: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
e080: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
e090: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
e0a0: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
e0b0: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
e0c0: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
e0d0: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
e0e0: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
e0f0: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
e100: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
e110: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
e120: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
e130: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
e140: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
e150: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
e160: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
e170: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
e180: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
e190: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
e1a0: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
e1b0: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
e1c0: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
e1d0: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
e1e0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
e1f0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e200: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
e210: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
e220: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
e230: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
e240: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e250: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e260: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
e270: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
e280: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
e290: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e2a0: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
e2b0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
e2c0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
e2d0: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
e2e0: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
e2f0: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
e300: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
e310: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
e320: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
e330: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
e340: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
e350: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
e360: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
e370: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
e380: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
e390: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
e3a0: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
e3b0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
e3c0: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
e3d0: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
e3e0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
e3f0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e400: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
e410: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
e420: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
e430: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
e440: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
e450: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
e460: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
e470: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
e480: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
e490: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
e4a0: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
e4b0: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
e4c0: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
e4d0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e4e0: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
e4f0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
e500: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
e510: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
e520: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
e530: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
e540: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
e550: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
e560: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
e570: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
e580: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
e590: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
e5a0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
e5b0: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
e5c0: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
e5d0: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
e5e0: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
e5f0: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
e600: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
e610: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
e620: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
e630: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
e640: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
e650: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
e660: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
e670: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
e680: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
e690: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
e6a0: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
e6b0: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
e6c0: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
e6d0: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
e6e0: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
e6f0: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
e700: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
e710: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
e720: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
e730: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
e740: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
e750: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
e760: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
e770: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
e780: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
e790: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
e7a0: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
e7b0: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
e7c0: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
e7d0: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
e7e0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
e7f0: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
e800: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
e810: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
e820: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
e830: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
e840: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
e850: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
e860: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
e870: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
e880: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
e890: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
e8a0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
e8b0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
e8c0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
e8d0: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
e8e0: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
e8f0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
e900: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
e910: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
e920: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
e930: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
e940: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
e950: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
e960: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
e970: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
e980: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
e990: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
e9a0: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
e9b0: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
e9c0: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
e9d0: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20  ** was given no 
e9e0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
e9f0: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
ea00: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
ea10: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
ea20: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
ea30: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
ea40: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
ea50: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
ea60: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
ea70: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
ea80: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
ea90: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
eaa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
eab0: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
eac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ead0: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
eae0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
eaf0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
eb00: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
eb10: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
eb20: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
eb30: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
eb40: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
eb50: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
eb60: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
eb70: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
eb80: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
eb90: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
eba0: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
ebb0: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
ebc0: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
ebd0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
ebe0: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
ebf0: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
ec00: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
ec10: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
ec20: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
ec30: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
ec40: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
ec50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
ec60: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
ec70: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
ec80: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
ec90: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
eca0: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
ecb0: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
ecc0: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
ecd0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ece0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
ecf0: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
ed00: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
ed10: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
ed20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ed30: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
ed40: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
ed50: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
ed60: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
ed70: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
ed80: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
ed90: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
eda0: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
edb0: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
edc0: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
edd0: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
ede0: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
edf0: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
ee00: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
ee10: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ee20: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
ee30: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
ee40: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
ee50: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
ee60: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
ee70: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
ee80: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
ee90: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
eea0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
eeb0: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
eec0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
eed0: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
eee0: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
eef0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
ef00: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
ef10: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
ef20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ef30: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
ef40: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
ef50: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
ef60: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
ef70: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
ef80: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
ef90: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
efa0: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
efb0: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
efc0: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
efd0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
efe0: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
eff0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
f000: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
f010: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
f020: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f030: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
f040: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
f050: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
f060: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
f070: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
f080: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
f090: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
f0a0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
f0b0: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
f0c0: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
f0d0: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
f0e0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
f0f0: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
f100: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
f110: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
f120: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
f130: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
f140: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
f150: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f160: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
f170: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
f180: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
f190: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
f1a0: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
f1b0: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
f1c0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f1d0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
f1e0: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
f1f0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f200: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
f210: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
f220: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
f230: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
f240: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
f250: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
f260: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
f270: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f280: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
f290: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
f2a0: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
f2b0: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
f2c0: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
f2d0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
f2e0: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
f2f0: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
f300: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
f310: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
f320: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
f330: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
f340: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
f350: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
f360: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
f370: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
f380: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
f390: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
f3a0: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
f3b0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
f3c0: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
f3d0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
f3e0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
f3f0: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
f400: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
f410: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
f420: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
f430: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
f440: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
f450: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
f460: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f470: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
f480: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
f490: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
f4a0: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
f4b0: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
f4c0: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
f4d0: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
f4e0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
f4f0: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
f500: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
f510: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
f520: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
f530: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
f540: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
f550: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
f560: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
f570: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f580: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
f590: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
f5a0: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
f5b0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f5c0: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
f5d0: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
f5e0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
f5f0: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
f600: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
f610: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
f620: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
f630: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
f640: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
f650: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
f660: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
f670: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
f680: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
f690: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
f6a0: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
f6b0: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
f6c0: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
f6d0: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
f6e0: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
f6f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
f700: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
f710: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
f720: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
f730: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
f740: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
f750: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
f760: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
f770: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
f780: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
f790: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
f7a0: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
f7b0: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
f7c0: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
f7d0: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
f7e0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
f7f0: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
f800: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
f810: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
f820: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
f830: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
f840: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
f850: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
f860: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
f870: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
f880: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
f890: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
f8a0: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
f8b0: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
f8c0: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
f8d0: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
f8e0: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
f8f0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
f900: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
f910: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
f920: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
f930: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
f940: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
f950: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f960: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
f970: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
f980: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
f990: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
f9a0: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
f9b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
f9c0: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
f9d0: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
f9e0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
f9f0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
fa00: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
fa10: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
fa20: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
fa30: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
fa40: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
fa50: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fa60: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
fa70: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
fa80: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
fa90: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
faa0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
fab0: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
fac0: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
fad0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
fae0: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
faf0: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
fb00: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
fb10: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
fb20: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
fb30: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
fb40: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
fb50: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
fb60: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
fb70: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
fb80: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
fb90: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
fba0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
fbb0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
fbc0: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
fbd0: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
fbe0: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
fbf0: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
fc00: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
fc10: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
fc20: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
fc30: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
fc40: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
fc50: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
fc60: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
fc70: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
fc80: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
fc90: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
fca0: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
fcb0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
fcc0: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
fcd0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
fce0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
fcf0: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
fd00: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
fd10: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
fd20: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
fd30: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
fd40: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
fd50: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
fd60: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
fd70: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
fd80: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
fd90: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
fda0: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
fdb0: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
fdc0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
fdd0: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
fde0: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
fdf0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
fe00: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
fe10: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
fe20: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
fe30: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
fe40: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
fe50: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
fe60: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
fe70: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
fe80: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
fe90: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
fea0: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
feb0: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
fec0: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
fed0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
fee0: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
fef0: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
ff00: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
ff10: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
ff20: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
ff30: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
ff40: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
ff50: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
ff60: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
ff70: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
ff80: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
ff90: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
ffa0: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
ffb0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
ffc0: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
ffd0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ffe0: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
fff0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
10000 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
10010 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
10020 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
10030 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
10040 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
10050 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
10060 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
10070 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
10080 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
10090 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
100a0 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
100b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
100c0 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
100d0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
100e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
100f0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10100 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
10110 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
10120 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
10130 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
10140 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
10150 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
10160 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
10170 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
10180 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
10190 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
101a0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
101b0 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
101c0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
101d0 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
101e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
101f0 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
10200 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
10210 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
10220 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
10230 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
10240 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
10250 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
10260 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
10270 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
10280 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
10290 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
102a0 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
102b0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
102c0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
102d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
102e0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ions.**.** The s
102f0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10300 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
10310 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
10320 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
10330 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
10340 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10350 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
10360 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
10370 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10380 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
10390 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
103a0 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
103b0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
103c0 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
103d0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
103e0 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
103f0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
10400 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
10410 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
10420 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
10430 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
10440 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
10450 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
10460 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
10470 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
10480 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
10490 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
104a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
104b0 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
104c0 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
104d0 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
104e0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
104f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
10500 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
10510 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
10520 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
10530 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
10540 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
10550 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
10560 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
10570 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
10580 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
10590 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
105a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
105b0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
105c0 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
105d0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
105e0 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
105f0 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
10600 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
10610 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
10620 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
10630 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
10640 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
10650 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
10660 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
10670 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10680 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
10690 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
106a0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
106b0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
106c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
106d0 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
106e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
106f0 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
10700 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
10710 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
10720 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
10730 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
10740 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
10750 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
10760 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
10770 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10780 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
10790 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
107a0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
107b0 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
107c0 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
107d0 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
107e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
107f0 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
10800 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
10810 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
10820 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
10830 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
10840 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
10850 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
10860 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
10870 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
10880 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
10890 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
108a0 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
108b0 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
108c0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
108d0 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
108e0 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
108f0 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
10900 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
10910 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
10920 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
10930 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
10940 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
10950 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
10960 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
10970 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
10980 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
10990 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
109a0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
109b0 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
109c0 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
109d0 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
109e0 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
109f0 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
10a00 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
10a10 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
10a20 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
10a30 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
10a40 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
10a50 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
10a60 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
10a70 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
10a80 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
10a90 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
10aa0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
10ab0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
10ac0 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
10ad0 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
10ae0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
10af0 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
10b00 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
10b10 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
10b20 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
10b30 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
10b40 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
10b50 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
10b60 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
10b70 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
10b80 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
10b90 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
10ba0 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
10bb0 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
10bc0 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
10bd0 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
10be0 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
10bf0 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
10c00 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
10c10 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
10c20 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
10c30 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
10c40 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
10c50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10c60 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
10c70 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
10c80 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
10c90 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
10ca0 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
10cb0 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
10cc0 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
10cd0 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
10ce0 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
10cf0 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
10d00 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
10d10 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
10d20 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
10d30 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
10d40 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
10d50 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
10d60 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
10d70 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
10d80 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
10d90 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
10da0 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
10db0 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
10dc0 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
10dd0 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
10de0 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
10df0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
10e00 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
10e10 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
10e20 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65  llocator.  For e
10e30 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69  xample,.** it mi
10e40 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79  ght allocate any
10e50 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73   require mutexes
10e60 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69   or initialize i
10e70 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20  nternal data.** 
10e80 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65  structures.  The
10e90 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
10ea0 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e  d is invoked (in
10eb0 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20  directly) by.** 
10ec0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
10ed0 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20  n()] and should 
10ee0 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  deallocate any r
10ef0 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65  esources acquire
10f00 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20  d.** by xInit.  
10f10 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69  The pAppData poi
10f20 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20  nter is used as 
10f30 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
10f40 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61  er to.** xInit a
10f50 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a  nd xShutdown..**
10f60 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73  .** SQLite holds
10f70 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
10f80 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
10f90 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20  ] mutex when it 
10fa0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78  invokes.** the x
10fb0 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20  Init method, so 
10fc0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
10fd0 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72   need not be thr
10fe0 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a  eadsafe.  The.**
10ff0 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
11000 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64  d is only called
11010 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
11020 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74  hutdown()] so it
11030 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65   does.** not nee
11040 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61  d to be threadsa
11050 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20  fe either.  For 
11060 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64  all other method
11070 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c  s, SQLite.** hol
11080 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
11090 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d  UTEX_STATIC_MEM]
110a0 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61   mutex as long a
110b0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
110c0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
110d0 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  S] configuration
110e0 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65   option is turne
110f0 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69  d on (which.** i
11100 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29  t is by default)
11110 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68   and so the meth
11120 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69  ods are automati
11130 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64  cally serialized
11140 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66  ..** However, if
11150 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
11160 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69  MEMSTATUS] is di
11170 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  sabled, then the
11180 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64   other.** method
11190 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  s must be thread
111a0 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b  safe or else mak
111b0 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61  e their own arra
111c0 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20  ngements for.** 
111d0 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  serialization..*
111e0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  *.** SQLite will
111f0 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49   never invoke xI
11200 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20  nit() more than 
11210 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20  once without an 
11220 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63  intervening.** c
11230 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e  all to xShutdown
11240 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
11250 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
11260 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
11270 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
11280 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
11290 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
112a0 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
112b0 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
112c0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
112d0 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
112e0 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
112f0 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
11300 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
11310 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
11320 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
11330 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
11340 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
11350 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
11360 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
11370 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
11380 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
11390 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
113a0 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
113b0 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
113c0 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
113d0 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
113e0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
113f0 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
11400 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
11410 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
11420 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
11430 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
11440 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
11450 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
11460 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
11470 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
11480 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
11490 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
114a0 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
114b0 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
114c0 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
114d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
114e0 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
114f0 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
11500 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f  S: {configuratio
11510 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20  n option}.**.** 
11520 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
11530 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
11540 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
11550 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
11560 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
11570 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
11580 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
11590 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
115a0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
115b0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
115c0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
115d0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
115e0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
115f0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
11600 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
11610 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
11620 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
11630 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
11640 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
11650 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
11660 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
11670 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
11680 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
11690 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
116a0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
116b0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
116c0 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
116d0 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
116e0 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
116f0 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
11700 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
11710 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
11720 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
11730 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
11740 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
11750 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  GLETHREAD]] <dt>
11760 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
11770 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a  NGLETHREAD</dt>.
11780 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
11790 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
117a0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
117b0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
117c0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
117d0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67  ng mode] to Sing
117e0 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  le-thread.  In o
117f0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
11800 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  isables.** all m
11810 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73  utexing and puts
11820 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d   SQLite into a m
11830 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e  ode where it can
11840 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a   only be used.**
11850 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
11860 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ead.   ^If SQLit
11870 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11880 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
11890 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
118a0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
118b0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
118c0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
118d0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
118e0 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  le to change the
118f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11900 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75  ] from its defau
11910 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53  lt.** value of S
11920 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64  ingle-thread and
11930 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   so [sqlite3_con
11940 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
11950 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rn .** [SQLITE_E
11960 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
11970 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
11980 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
11990 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  EAD.** configura
119a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
119b0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
119c0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
119d0 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
119e0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
119f0 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
11a00 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
11a10 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
11a20 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
11a30 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
11a40 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11a50 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
11a60 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
11a70 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
11a80 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
11a90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11aa0 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
11ab0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
11ac0 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
11ad0 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
11ae0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
11af0 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
11b00 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
11b10 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
11b20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11b30 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
11b40 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
11b50 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
11b60 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
11b70 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
11b80 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
11b90 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
11ba0 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
11bb0 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
11bc0 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
11bd0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
11be0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
11bf0 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
11c00 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
11c10 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
11c20 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
11c30 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
11c40 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
11c50 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
11c60 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
11c70 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
11c80 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
11c90 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
11ca0 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
11cb0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
11cc0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
11cd0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
11ce0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
11cf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
11d00 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
11d10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
11d20 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11d30 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
11d40 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ZED]] <dt>SQLITE
11d50 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
11d60 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
11d70 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
11d80 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
11d90 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
11da0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
11db0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11dc0 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20   to Serialized. 
11dd0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11de0 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62  this option enab
11df0 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
11e00 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65  es including the
11e10 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75   recursive.** mu
11e20 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61  texes on [databa
11e30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
11e40 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
11e50 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
11e60 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65  .** In this mode
11e70 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64   (which is the d
11e80 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69  efault when SQLi
11e90 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11ea0 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  ith.** [SQLITE_T
11eb0 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68  HREADSAFE=1]) th
11ec0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
11ed0 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72   will itself ser
11ee0 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a  ialize access.**
11ef0 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
11f00 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
11f10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11f20 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65  nts] so that the
11f30 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
11f40 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74  is free to use t
11f50 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
11f60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72  e connection] or
11f70 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72   the.** same [pr
11f80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11f90 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74  ] in different t
11fa0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
11fb0 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20  me time..** ^If 
11fc0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11fd0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11fe0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11ff0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
12000 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12010 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12020 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
12030 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
12040 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74  he Serialized [t
12050 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
12060 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
12070 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
12080 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
12090 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
120a0 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
120b0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
120c0 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ED configuration
120d0 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
120e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
120f0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  FIG_MALLOC]] <dt
12100 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
12110 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
12120 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
12130 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70  CONFIG_MALLOC op
12140 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12150 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
12160 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  ch is .** a poin
12170 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
12180 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
12190 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
121a0 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
121b0 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
121c0 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
121d0 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
121e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
121f0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
12200 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
12210 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
12220 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
12230 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
12240 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d  ite.)^ ^SQLite m
12250 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20  akes.** its own 
12260 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
12270 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
12280 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12290 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
122a0 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65  re.** before the
122b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
122c0 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  ()] call returns
122d0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
122e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
122f0 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
12300 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
12310 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
12320 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
12330 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
12340 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
12350 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
12360 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
12370 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
12380 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
12390 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
123a0 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
123b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
123c0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
123d0 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
123e0 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
123f0 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
12400 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
12410 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
12420 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
12430 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
12440 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
12450 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
12460 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
12470 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
12480 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
12490 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
124a0 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
124b0 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
124c0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64  or example. </dd
124d0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
124e0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
124f0 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  S]] <dt>SQLITE_C
12500 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
12510 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
12520 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12530 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e  MEMSTATUS option
12540 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
12550 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
12560 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  nt,.** interpret
12570 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c  ed as a boolean,
12580 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
12590 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
125a0 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20  ollection of.** 
125b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
125c0 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  n statistics. ^(
125d0 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
125e0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
125f0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20  s are disabled, 
12600 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  the .** followin
12610 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
12620 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
12630 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
12640 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
12650 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
12660 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
12670 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12680 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
12690 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
126a0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
126b0 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
126c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
126d0 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
126e0 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
126f0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
12700 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
12710 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
12720 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
12730 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
12740 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
12750 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
12760 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
12770 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
12780 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
12790 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
127a0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
127b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
127c0 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
127d0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
127e0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
127f0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
12800 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e  G_SCRATCH option
12810 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
12820 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
12830 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  r.** that SQLite
12840 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72   can use for scr
12850 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28  atch memory.  ^(
12860 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
12870 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20  arguments.** to 
12880 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
12890 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65  RATCH:  A pointe
128a0 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
128b0 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
128c0 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
128d0 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
128e0 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
128f0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
12900 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
12910 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
12920 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
12930 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
12940 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
12950 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54  ions (N).)^.** T
12960 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12970 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
12980 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
12990 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
129a0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
129b0 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
129c0 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
129d0 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72  will not use mor
129e0 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74  e than one scrat
129f0 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
12a00 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74  hread..** ^SQLit
12a10 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
12a20 75 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62  uest a scratch b
12a30 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
12a40 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
12a50 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
12a60 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  page size..** ^I
12a70 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
12a80 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
12a90 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
12aa0 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
12ab0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
12ac0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
12ad0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
12ae0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
12af0 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
12b00 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
12b10 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e  emory needed.<p>
12b20 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70  .** ^When the ap
12b30 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64  plication provid
12b40 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66  es any amount of
12b50 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
12b60 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f  using.** SQLITE_
12b70 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20  CONFIG_SCRATCH, 
12b80 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e  SQLite avoids un
12b90 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a  necessary large.
12ba0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
12bb0 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69  oc|heap allocati
12bc0 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61  ons]..** This ca
12bd0 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70  n help [Robson p
12be0 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d  roof|prevent mem
12bf0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
12c00 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20  ailures] due to 
12c10 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74  heap.** fragment
12c20 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d  ation in low-mem
12c30 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73  ory embedded sys
12c40 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  tems..** </dd>.*
12c50 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12c60 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d  NFIG_PAGECACHE]]
12c70 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12c80 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
12c90 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
12ca0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
12cb0 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70  ECACHE option sp
12cc0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
12cd0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a   memory buffer.*
12ce0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  * that SQLite ca
12cf0 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61  n use for the da
12d00 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
12d10 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
12d20 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  lt page.** cache
12d30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
12d40 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
12d50 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  guration should 
12d60 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61  not be used if a
12d70 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
12d80 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
12d90 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
12da0 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
12db0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
12dc0 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a  NFIG_PCACHE2].**
12dd0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12de0 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65  ption..** ^There
12df0 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
12e00 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43  ents to SQLITE_C
12e10 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a  ONFIG_PAGECACHE:
12e20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
12e30 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
12e40 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
12e50 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
12e60 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
12e70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
12e80 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
12e90 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
12ea0 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
12eb0 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
12ec0 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
12ed0 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
12ee0 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
12ef0 37 36 38 29 20 70 6c 75 73 20 73 6f 6d 65 20 65  768) plus some e
12f00 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 65  xtra bytes for e
12f10 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64  ach.** page head
12f20 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72  er.  ^The number
12f30 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 20   of extra bytes 
12f40 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70 61  needed by the pa
12f50 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e  ge header.** can
12f60 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
12f70 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
12f80 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
12f90 44 52 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a  DRSZ] option .**
12fa0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
12fb0 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69  fig()]..** ^It i
12fc0 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
12fd0 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
12fe0 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72  d memory,.** for
12ff0 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65   the sz paramete
13000 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74  r to be larger t
13010 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20  han necessary.  
13020 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
13030 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
13040 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
13050 65 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20  e aligned block 
13060 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61 74 0a 2a  of memory that.*
13070 2a 20 69 73 20 61 74 20 6c 65 61 73 74 20 73 7a  * is at least sz
13080 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
13090 72 79 2c 20 6f 74 68 65 72 77 69 73 65 20 73 75  ry, otherwise su
130a0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
130b0 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
130c0 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  d..** ^SQLite wi
130d0 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  ll use the memor
130e0 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  y provided by th
130f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13100 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a   to satisfy its.
13110 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20  ** memory needs 
13120 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20  for the first N 
13130 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64  pages that it ad
13140 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49  ds to cache.  ^I
13150 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
13160 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
13170 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
13180 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
13190 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
131a0 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
131b0 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
131c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
131d0 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
131e0 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 3c   storage space.<
131f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13200 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
13210 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13220 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
13230 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
13240 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70  E_CONFIG_HEAP op
13250 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
13260 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
13270 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53  uffer .** that S
13280 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66  QLite will use f
13290 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
132a0 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
132b0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a  ocation needs.**
132c0 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
132d0 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53  ovided for by [S
132e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
132f0 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATCH] and [SQLIT
13300 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
13310 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c  HE]..** ^The SQL
13320 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
13330 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
13340 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
13350 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a  te is compiled.*
13360 2a 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53  * with either [S
13370 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
13380 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45  SYS3] or [SQLITE
13390 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
133a0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
133b0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
133c0 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77  f invoked otherw
133d0 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61  ise..** ^There a
133e0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
133f0 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ts to SQLITE_CON
13400 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20  FIG_HEAP:.** An 
13410 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
13420 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
13430 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
13440 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
13450 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
13460 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
13470 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
13480 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
13490 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
134a0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
134b0 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
134c0 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
134d0 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
134e0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
134f0 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
13500 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
13510 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
13520 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
13530 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
13540 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13550 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
13560 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
13570 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
13580 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61  then the alterna
13590 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tive memory.** a
135a0 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61  llocator is enga
135b0 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c  ged to handle al
135c0 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d  l of SQLites mem
135d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
135e0 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  eeds..** The fir
135f0 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
13600 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
13610 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
13620 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
13630 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
13640 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
13650 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  of SQLite will b
13660 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
13670 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  The minimum allo
13680 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63  cation size is c
13690 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20  apped at 2**12. 
136a0 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65  Reasonable value
136b0 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e  s.** for the min
136c0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
136d0 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68  size are 2**5 th
136e0 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e  rough 2**8.</dd>
136f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13700 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c  CONFIG_MUTEX]] <
13710 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13720 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
13730 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
13740 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70  _CONFIG_MUTEX op
13750 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
13760 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
13770 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  ch is a.** point
13780 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
13790 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
137a0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
137b0 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
137c0 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
137d0 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76  ifies alternativ
137e0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65  e low-level mute
137f0 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  x routines to be
13800 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a   used in place.*
13810 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74  * the mutex rout
13820 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
13830 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69  SQLite.)^  ^SQLi
13840 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
13850 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e  of the.** conten
13860 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
13870 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
13880 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72   structure befor
13890 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  e the call to.**
138a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
138b0 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66  ()] returns. ^If
138c0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
138d0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
138e0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
138f0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
13900 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
13910 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
13920 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
13930 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
13940 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
13950 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
13960 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
13970 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13980 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
13990 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
139a0 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
139b0 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
139c0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
139d0 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
139e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
139f0 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64  IG_GETMUTEX]] <d
13a00 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13a10 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  GETMUTEX</dt>.**
13a20 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
13a30 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
13a40 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
13a50 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13a60 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
13a70 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
13a80 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
13a90 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13aa0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
13ab0 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
13ac0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
13ad0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
13ae0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
13af0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
13b00 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
13b10 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
13b20 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
13b30 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
13b40 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
13b50 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
13b60 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
13b70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
13b80 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
13b90 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
13ba0 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
13bb0 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
13bc0 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
13bd0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13be0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
13bf0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
13c00 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13c10 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
13c20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
13c30 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
13c40 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
13c50 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
13c60 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
13c70 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
13c80 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13c90 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
13ca0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
13cb0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13cc0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
13cd0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
13ce0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
13cf0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
13d00 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53  OOKASIDE]] <dt>S
13d10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
13d20 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
13d30 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
13d40 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
13d50 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  E option takes t
13d60 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
13d70 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74  t determine.** t
13d80 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20  he default size 
13d90 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  of lookaside mem
13da0 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74  ory on each [dat
13db0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13dc0 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  ]..** The first 
13dd0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
13de0 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
13df0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
13e00 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65   slot and the se
13e10 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62  cond is the numb
13e20 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61  er of.** slots a
13e30 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68  llocated to each
13e40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13e50 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54  tion.)^  ^(SQLIT
13e60 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
13e70 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c  DE.** sets the <
13e80 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
13e90 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
13ea0 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
13eb0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
13ec0 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69   option to [sqli
13ed0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
13ee0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
13ef0 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
13f00 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
13f10 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
13f20 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
13f30 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
13f40 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13f50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
13f60 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13f70 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
13f80 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
13f90 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69  FIG_PCACHE2 opti
13fa0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
13fb0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
13fc0 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
13fd0 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33  r to an [sqlite3
13fe0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
13ff0 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
14000 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
14010 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63  .** the interfac
14020 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  e to a custom pa
14030 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
14040 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53  ntation.)^.** ^S
14050 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
14060 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
14070 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
14080 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e  s2] object.</dd>
14090 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
140a0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
140b0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
140c0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
140d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
140e0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
140f0 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74  G_GETPCACHE2 opt
14100 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14110 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
14120 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
14130 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33  r to an [sqlite3
14140 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
14150 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74  ] object.  SQLit
14160 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20  e copies of the 
14170 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20  current.** page 
14180 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
14190 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f  tion into that o
141a0 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  bject.)^ </dd>.*
141b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
141c0 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53  NFIG_LOG]] <dt>S
141d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
141e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68  </dt>.** <dd> Th
141f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14200 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  LOG option is us
14210 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
14220 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c  the SQLite.** gl
14230 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d  obal [error log]
14240 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54  ..** (^The SQLIT
14250 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
14260 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
14270 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74  guments: a point
14280 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74  er to a.** funct
14290 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20  ion with a call 
142a0 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69  signature of voi
142b0 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  d(*)(void*,int,c
142c0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a  onst char*), .**
142d0 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74   and a pointer t
142e0 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20  o void. ^If the 
142f0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
14300 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74   is not NULL, it
14310 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62   is.** invoked b
14320 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  y [sqlite3_log()
14330 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63  ] to process eac
14340 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e  h logging event.
14350 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e    ^If the.** fun
14360 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
14370 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69   NULL, the [sqli
14380 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72  te3_log()] inter
14390 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e  face becomes a n
143a0 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f  o-op..** ^The vo
143b0 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  id pointer that 
143c0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
143d0 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45  gument to SQLITE
143e0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a  _CONFIG_LOG is.*
143f0 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  * passed through
14400 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61   as the first pa
14410 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
14420 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
14430 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
14440 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74  ction whenever t
14450 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  hat function is 
14460 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73  invoked.  ^The s
14470 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
14480 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72  to.** the logger
14490 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63   function is a c
144a0 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74  opy of the first
144b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
144c0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
144d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  ** [sqlite3_log(
144e0 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69  )] call and is i
144f0 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20  ntended to be a 
14500 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
14510 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   an.** [extended
14520 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20   result code].  
14530 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
14540 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  eter passed to t
14550 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20  he logger is.** 
14560 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65  log message afte
14570 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61  r formatting via
14580 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
14590 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51  tf()]..** The SQ
145a0 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74  Lite logging int
145b0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
145c0 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67  entrant; the log
145d0 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ger function.** 
145e0 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20  supplied by the 
145f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
14600 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20   not invoke any 
14610 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
14620 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d  ..** In a multi-
14630 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
14640 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63  tion, the applic
14650 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
14660 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
14670 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
14680 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  afe. </dd>.**.**
14690 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
146a0 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _URI]] <dt>SQLIT
146b0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20  E_CONFIG_URI.** 
146c0 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45  <dd>^(The SQLITE
146d0 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69  _CONFIG_URI opti
146e0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
146f0 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
14700 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f  pe int..** If no
14710 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49  n-zero, then URI
14720 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
14730 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49  bally enabled. I
14740 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
14750 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  is zero,.** then
14760 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
14770 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
14780 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61  ed.)^ ^If URI ha
14790 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
147a0 6c 79 20 65 6e 61 62 6c 65 64 2c 0a 2a 2a 20 61  ly enabled,.** a
147b0 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73  ll filenames pas
147c0 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
147d0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
147e0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73  3_open_v2()], [s
147f0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
14800 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
14810 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
14820 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
14830 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
14840 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
14850 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
14860 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
14870 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
14880 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
14890 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
148a0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
148b0 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c  ed. ^If it is gl
148c0 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c  obally disabled,
148d0 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a   filenames are.*
148e0 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74  * only interpret
148f0 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68  ed as URIs if th
14900 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52  e SQLITE_OPEN_UR
14910 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  I flag is set wh
14920 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  en the.** databa
14930 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
14940 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65   opened. ^(By de
14950 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
14960 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
14970 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
14980 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
14990 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
149a0 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
149b0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
149c0 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
149d0 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  efined.)^.**.** 
149e0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
149f0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
14a00 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CAN]] <dt>SQLITE
14a10 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
14a20 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c  _INDEX_SCAN.** <
14a30 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
14a40 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
14a50 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e  NDEX_SCAN option
14a60 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
14a70 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d  integer.** argum
14a80 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
14a90 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
14aa0 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74  olean in order t
14ab0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
14ac0 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  ble.** the use o
14ad0 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
14ae0 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
14af0 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71  e scans in the q
14b00 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a  uery optimizer..
14b10 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
14b20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
14b30 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
14b40 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
14b50 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
14b60 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
14b70 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
14b80 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
14b90 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14ba0 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
14bb0 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
14bc0 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
14bd0 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
14be0 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
14bf0 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
14c00 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
14c10 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
14c20 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
14c30 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
14c40 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  ion.** when the 
14c50 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
14c60 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
14c70 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
14c80 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
14c90 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
14ca0 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
14cb0 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
14cc0 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
14cd0 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
14ce0 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
14cf0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
14d00 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
14d10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14d20 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
14d30 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
14d40 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
14d50 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
14d60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14d70 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
14d80 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
14d90 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
14da0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
14db0 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
14dc0 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
14dd0 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
14de0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
14df0 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
14e00 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ops..** </dd>.**
14e10 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14e20 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
14e30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14e40 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
14e50 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
14e60 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
14e70 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
14e80 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
14e90 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
14ea0 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65  QLLOG] pre-proce
14eb0 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
14ec0 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
14ed0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
14ee0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
14ef0 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
14f00 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
14f10 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
14f20 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
14f30 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
14f40 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
14f50 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
14f60 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
14f70 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
14f80 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
14f90 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
14fa0 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
14fb0 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
14fc0 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
14fd0 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
14fe0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
14ff0 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
15000 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
15010 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
15020 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
15030 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
15040 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
15050 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
15060 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
15070 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
15080 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
15090 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
150a0 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
150b0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
150c0 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
150d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
150e0 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
150f0 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
15100 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
15110 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
15120 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
15130 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
15140 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
15150 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
15160 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
15170 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
15180 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
15190 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
151a0 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
151b0 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20  L In this case. 
151c0 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75   An example of u
151d0 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e  sing this.** con
151e0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
151f0 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  n can be seen in
15200 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f   the "test_sqllo
15210 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  g.c" source file
15220 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e   in.** the canon
15230 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72  ical SQLite sour
15240 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a  ce tree.</dd>.**
15250 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15260 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  FIG_MMAP_SIZE]].
15270 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
15280 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a  NFIG_MMAP_SIZE.*
15290 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f  * <dd>^SQLITE_CO
152a0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74  NFIG_MMAP_SIZE t
152b0 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20  akes two 64-bit 
152c0 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33  integer (sqlite3
152d0 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a  _int64) values.*
152e0 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64  * that are the d
152f0 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65  efault mmap size
15300 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61   limit (the defa
15310 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a  ult setting for.
15320 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  ** [PRAGMA mmap_
15330 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d  size]) and the m
15340 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
15350 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a  map size limit..
15360 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
15370 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f  setting can be o
15380 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63  verridden by eac
15390 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
153a0 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65  ction using.** e
153b0 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d  ither the [PRAGM
153c0 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d  A mmap_size] com
153d0 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e  mand, or by usin
153e0 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
153f0 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
15400 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20  ] file control. 
15410 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61   ^(The maximum a
15420 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
15430 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65  .** will be sile
15440 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69  ntly truncated i
15450 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74  f necessary so t
15460 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  hat it does not 
15470 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f  exceed the.** co
15480 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d  mpile-time maxim
15490 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74  um mmap size set
154a0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
154b0 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45  TE_MAX_MMAP_SIZE
154c0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
154d0 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20  ption.)^.** ^If 
154e0 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20  either argument 
154f0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  to this option i
15500 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
15510 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69   that argument i
15520 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20  s.** changed to 
15530 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  its compile-time
15540 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
15550 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15560 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d  WIN32_HEAPSIZE]]
15570 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
15580 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
15590 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SIZE.** <dd>^The
155a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
155b0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70  IN32_HEAPSIZE op
155c0 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
155d0 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
155e0 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
155f0 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68  for Windows with
15600 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
15610 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
15620 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
15630 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 49  efined..** ^SQLI
15640 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15650 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61  HEAPSIZE takes a
15660 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   32-bit unsigned
15670 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a   integer value.*
15680 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  * that specifies
15690 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a   the maximum siz
156a0 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64  e of the created
156b0 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a   heap..** </dl>.
156c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
156d0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
156e0 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  SZ]].** <dt>SQLI
156f0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15700 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54  _HDRSZ.** <dd>^T
15710 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15720 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70  _PCACHE_HDRSZ op
15730 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
15740 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
15750 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
15760 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
15770 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74  r and writes int
15780 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74  o that integer t
15790 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
157a0 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20  ra.** bytes per 
157b0 70 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f  page required fo
157c0 72 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b  r each page in [
157d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
157e0 47 45 43 41 43 48 45 5d 2e 20 54 68 65 20 61 6d  GECACHE]. The am
157f0 6f 75 6e 74 20 6f 66 0a 2a 2a 20 65 78 74 72 61  ount of.** extra
15800 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20   space required 
15810 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e  can change depen
15820 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70  ding on the comp
15830 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20  iler,.** target 
15840 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51  platform, and SQ
15850 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a  Lite version..**
15860 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
15870 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15880 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
15890 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
158a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
158b0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
158c0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
158d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
158e0 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
158f0 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
15900 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15910 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
15920 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
15930 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
15940 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15950 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
15960 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
15970 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
15980 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15990 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
159a0 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
159b0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
159c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
159d0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
159e0 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
159f0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
15a00 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
15a10 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
15a20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
15a30 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
15a40 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
15a50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15a60 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
15a70 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
15a80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15a90 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
15aa0 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
15ab0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
15ac0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
15ad0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
15ae0 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
15af0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
15b00 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
15b10 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
15b20 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
15b30 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
15b40 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
15b50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15b60 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
15b70 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
15b80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15b90 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
15ba0 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70      14  /* no-op
15bb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15bc0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
15bd0 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f  CHE    15  /* no
15be0 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
15bf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
15c00 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
15c10 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
15c20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15c30 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
15c40 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
15c50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15c60 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
15c70 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69       18  /* sqli
15c80 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
15c90 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
15ca0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15cb0 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f  TPCACHE2   19  /
15cc0 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
15cd0 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
15ce0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15cf0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
15d00 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69  EX_SCAN 20  /* i
15d10 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
15d20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
15d30 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20  OG       21  /* 
15d40 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a  xSqllog, void* *
15d50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15d60 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
15d70 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69  E    22  /* sqli
15d80 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74  te3_int64, sqlit
15d90 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66  e3_int64 */.#def
15da0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15db0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15dc0 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74        23  /* int
15dd0 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e   nByte */.#defin
15de0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15df0 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20  PCACHE_HDRSZ    
15e00 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a      24  /* int *
15e10 70 73 7a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  psz */../*.** CA
15e20 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
15e30 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66   Connection Conf
15e40 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
15e50 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
15e60 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
15e70 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
15e80 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
15e90 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
15ea0 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
15eb0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
15ec0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
15ed0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
15ee0 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
15ef0 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
15f00 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
15f10 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
15f20 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
15f30 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
15f40 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
15f50 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
15f60 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
15f70 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
15f80 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
15f90 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
15fa0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  rom [sqlite3_db_
15fb0 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
15fc0 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
15fd0 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
15fe0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64   ^The [sqlite3_d
15ff0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
16000 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
16010 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
16020 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
16030 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
16040 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
16050 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
16060 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
16070 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
16080 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
16090 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
160a0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
160b0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68   option takes th
160c0 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  ree additional a
160d0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
160e0 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20  termine the .** 
160f0 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
16100 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
16110 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74  figuration for t
16120 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
16130 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68  nection]..** ^Th
16140 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16150 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61   (the third para
16160 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
16170 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
16180 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
16190 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  o a memory buffe
161a0 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f  r to use for loo
161b0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a  kaside memory..*
161c0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
161d0 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20  ument after the 
161e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
161f0 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a  LOOKASIDE verb.*
16200 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e  * may be NULL in
16210 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69   which case SQLi
16220 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65  te will allocate
16230 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64   the.** lookasid
16240 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20  e buffer itself 
16250 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
16260 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73  alloc()]. ^The s
16270 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
16280 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
16290 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
162a0 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54  buffer slot.  ^T
162b0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
162c0 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  t is the number 
162d0 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68  of.** slots.  Th
162e0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  e size of the bu
162f0 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  ffer in the firs
16300 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
16310 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a  be greater than.
16320 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74  ** or equal to t
16330 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68  he product of th
16340 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69  e second and thi
16350 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54  rd arguments.  T
16360 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73  he buffer.** mus
16370 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
16380 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
16390 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63  ry.  ^If the sec
163a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
163b0 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ** SQLITE_DBCONF
163c0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20  IG_LOOKASIDE is 
163d0 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f  not a multiple o
163e0 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72  f 8, it is inter
163f0 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64  nally.** rounded
16400 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78   down to the nex
16410 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70  t smaller multip
16420 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20  le of 8.  ^(The 
16430 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
16440 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
16450 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65  n for a database
16460 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20   connection can 
16470 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20  only be changed 
16480 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e  when that.** con
16490 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63  nection is not c
164a0 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c  urrently using l
164b0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c  ookaside memory,
164c0 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72   or in other wor
164d0 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22  ds.** when the "
164e0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72  current value" r
164f0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
16500 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73  qlite3_db_status
16510 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ](D,[SQLITE_CONF
16520 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e  IG_LOOKASIDE],..
16530 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41  .) is zero..** A
16540 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68  ny attempt to ch
16550 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
16560 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67  de memory config
16570 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f  uration when loo
16580 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79  kaside.** memory
16590 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65   is in use leave
165a0 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  s the configurat
165b0 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e  ion unchanged an
165c0 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53  d returns .** [S
165d0 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f  QLITE_BUSY].)^</
165e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
165f0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
16600 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a  ABLE_FKEY</dt>.*
16610 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
16620 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
16630 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
16640 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74   the enforcement
16650 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   of.** [foreign 
16660 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d  key constraints]
16670 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  .  There should 
16680 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
16690 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
166a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
166b0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
166c0 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
166d0 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  isable FK enforc
166e0 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69  ement,.** positi
166f0 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20  ve to enable FK 
16700 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e  enforcement or n
16710 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
16720 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a   FK enforcement.
16730 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  ** unchanged.  T
16740 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16750 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
16760 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
16770 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
16780 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
16790 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
167a0 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  er FK enforcemen
167b0 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a  t is off or on.*
167c0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
167d0 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
167e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
167f0 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
16800 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
16810 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f  case the FK enfo
16820 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20  rcement setting 
16830 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
16840 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
16850 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
16860 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
16870 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  GGER</dt>.** <dd
16880 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
16890 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
168a0 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45   or disable [CRE
168b0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
168c0 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72  iggers]..** Ther
168d0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
168e0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
168f0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
16900 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
16910 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
16920 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
16930 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73  triggers,.** pos
16940 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
16950 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61  triggers or nega
16960 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
16970 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
16980 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
16990 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
169a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
169b0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
169c0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
169d0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
169e0 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67  ate whether trig
169f0 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65  gers are disable
16a00 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
16a10 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
16a20 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
16a30 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
16a40 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
16a50 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
16a60 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73  se the trigger s
16a70 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
16a80 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
16a90 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
16aa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16ab0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
16ac0 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20  IDE       1001  
16ad0 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74  /* void* int int
16ae0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16af0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
16b00 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32  LE_FKEY     1002
16b10 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
16b20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16b30 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
16b40 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f  TRIGGER  1003  /
16b50 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a  * int int* */...
16b60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16b70 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
16b80 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
16b90 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  t Codes.**.** ^T
16ba0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
16bb0 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
16bc0 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
16bd0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
16be0 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
16bf0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
16c00 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
16c10 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
16c20 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
16c30 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
16c40 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
16c50 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
16c60 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ity..*/.int sqli
16c70 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
16c80 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
16c90 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
16ca0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16cb0 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
16cc0 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  id.**.** ^Each e
16cd0 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c  ntry in most SQL
16ce0 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65  ite tables (exce
16cf0 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20  pt for [WITHOUT 
16d00 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a  ROWID] tables).*
16d10 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  * has a unique 6
16d20 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
16d30 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
16d40 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
16d50 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
16d60 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
16d70 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
16d80 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
16d90 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
16da0 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
16db0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
16dc0 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
16dd0 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
16de0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
16df0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
16e00 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
16e10 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
16e20 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
16e30 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
16e40 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
16e50 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
16e60 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
16e70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
16e80 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
16e90 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 72  d(D) interface r
16ea0 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
16eb0 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f  d] of the .** mo
16ec0 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73  st recent succes
16ed0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
16ee0 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65  to a rowid table
16ef0 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62   or [virtual tab
16f00 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61  le].** on databa
16f10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
16f20 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74  .** ^Inserts int
16f30 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  o [WITHOUT ROWID
16f40 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74  ] tables are not
16f50 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49   recorded..** ^I
16f60 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
16f70 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72  [INSERT]s into r
16f80 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68  owid tables.** h
16f90 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
16fa0 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  d on the databas
16fb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20  e connection D, 
16fc0 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
16fd0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
16fe0 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65  id(D) returns ze
16ff0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  ro..**.** ^(If a
17000 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72  n [INSERT] occur
17010 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
17020 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b  er or within a [
17030 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
17040 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  * method, then t
17050 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
17060 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77   return the [row
17070 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
17080 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f  ted.** row as lo
17090 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
170a0 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
170b0 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e  le method is run
170c0 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
170d0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
170e0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
170f0 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20  ethod ends, the 
17100 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a  value returned .
17110 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
17120 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68  ne reverts to wh
17130 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65  at it was before
17140 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
17150 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65  virtual.** table
17160 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e   method began.)^
17170 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
17180 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
17190 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
171a0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
171b0 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
171c0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
171d0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
171e0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
171f0 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
17200 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
17210 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
17220 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
17230 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
17240 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
17250 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
17260 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
17270 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
17280 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
17290 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
172a0 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
172b0 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
172c0 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
172d0 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
172e0 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
172f0 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
17300 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
17310 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
17320 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
17330 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
17340 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
17350 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
17360 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
17370 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
17380 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
17390 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
173a0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
173b0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
173c0 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
173d0 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
173e0 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
173f0 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
17400 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
17410 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
17420 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
17430 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
17440 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
17450 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
17460 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
17470 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
17480 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
17490 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
174a0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
174b0 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
174c0 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
174d0 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
174e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
174f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
17500 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
17510 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
17520 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
17530 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
17540 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
17550 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
17560 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
17570 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
17580 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
17590 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
175a0 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
175b0 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
175c0 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
175d0 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
175e0 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c   [rowid]..*/.sql
175f0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
17600 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
17610 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
17620 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17630 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
17640 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
17650 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
17660 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
17670 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
17680 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73  ws modified, ins
17690 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65  erted or.** dele
176a0 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
176b0 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
176c0 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
176d0 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  E or DELETE.** s
176e0 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20  tatement on the 
176f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17700 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79  ion specified by
17710 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
17720 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69  ter..** ^Executi
17730 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
17740 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
17750 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69  nt does not modi
17760 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  fy the value.** 
17770 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
17780 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
17790 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d   ^Only changes m
177a0 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20  ade directly by 
177b0 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41  the INSERT, UPDA
177c0 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
177d0 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f  tement are.** co
177e0 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c  nsidered - auxil
177f0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
17800 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54  sed by [CREATE T
17810 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
17820 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  s], .** [foreign
17830 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72   key actions] or
17840 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
17850 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
17860 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
17870 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73  ..** .** Changes
17880 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
17890 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20  are intercepted 
178a0 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20  by .** [INSTEAD 
178b0 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53  OF trigger | INS
178c0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73  TEAD OF triggers
178d0 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
178e0 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a  d. ^The value .*
178f0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
17900 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
17910 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65  immediately afte
17920 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  r an INSERT, UPD
17930 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54  ATE or .** DELET
17940 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20  E statement run 
17950 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77  on a view is alw
17960 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63  ays zero. Only c
17970 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72  hanges made to r
17980 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61  eal .** tables a
17990 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
179a0 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72  * Things are mor
179b0 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66  e complicated if
179c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
179d0 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
179e0 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77  is.** executed w
179f0 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70  hile a trigger p
17a00 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e  rogram is runnin
17a10 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70  g. This may happ
17a20 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f  en if the.** pro
17a30 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63  gram uses the [c
17a40 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
17a50 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f  ction], or if so
17a60 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63  me other callbac
17a70 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e  k.** function in
17a80 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68  vokes sqlite3_ch
17a90 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79  anges() directly
17aa0 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a  . Essentially:.*
17ab0 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  * .** <ul>.**   
17ac0 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e  <li> ^(Before en
17ad0 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72  tering a trigger
17ae0 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c   program the val
17af0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ue returned by.*
17b00 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33  *        sqlite3
17b10 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
17b20 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66  ion is saved. Af
17b30 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20  ter the trigger 
17b40 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20  program .**     
17b50 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c     has finished,
17b60 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61   the original va
17b70 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e  lue is restored.
17b80 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e  )^.** .**   <li>
17b90 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67   ^(Within a trig
17ba0 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68  ger program each
17bb0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
17bc0 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20  and DELETE .**  
17bd0 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20        statement 
17be0 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72  sets the value r
17bf0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
17c00 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
17c10 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d          upon com
17c20 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61  pletion as norma
17c30 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68  l. Of course, th
17c40 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f  is value will no
17c50 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20  t include .**   
17c60 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73       any changes
17c70 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75   performed by su
17c80 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74  b-triggers, as t
17c90 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
17ca0 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
17cb0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61  value will be sa
17cc0 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64  ved and restored
17cd0 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d   after each sub-
17ce0 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e  trigger has run.
17cf0 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a  )^.** </ul>.** .
17d00 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74  ** ^This means t
17d10 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67  hat if the chang
17d20 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
17d30 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69  n (or similar) i
17d40 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65  s used.** by the
17d50 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55   first INSERT, U
17d60 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
17d70 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
17d80 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a   a trigger, it .
17d90 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  ** returns the v
17da0 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e  alue as set when
17db0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61   the calling sta
17dc0 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65  tement began exe
17dd0 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69  cuting..** ^If i
17de0 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  t is used by the
17df0 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65   second or subse
17e00 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65  quent such state
17e10 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72  ment within a tr
17e20 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61  igger .** progra
17e30 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  m, the value ret
17e40 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74  urned reflects t
17e50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
17e60 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68  s modified by th
17e70 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49  e .** previous I
17e80 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
17e90 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
17ea0 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
17eb0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a  e trigger..**.**
17ec0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
17ed0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
17ee0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
17ef0 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
17f00 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
17f10 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
17f20 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
17f30 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
17f40 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
17f50 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
17f60 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
17f70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
17f80 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
17f90 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
17fa0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
17fb0 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
17fc0 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
17fd0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
17fe0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
17ff0 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  te3_changes(sqli
18000 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
18010 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75  PI3REF: Total Nu
18020 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
18030 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
18040 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
18050 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  ns the total num
18060 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65  ber of rows inse
18070 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f  rted, modified o
18080 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
18090 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  all [INSERT], [U
180a0 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
180b0 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f  E] statements co
180c0 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65  mpleted.** since
180d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
180e0 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65  nnection was ope
180f0 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74  ned, including t
18100 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73  hose executed as
18110 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67  .** part of trig
18120 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45  ger programs. ^E
18130 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
18140 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
18150 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73  tatement.** does
18160 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20   not affect the 
18170 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
18180 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
18190 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a  changes()..** .*
181a0 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20  * ^Changes made 
181b0 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65  as part of [fore
181c0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
181d0 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e   are included in
181e0 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62   the.** count, b
181f0 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73  ut those made as
18200 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45   part of REPLACE
18210 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
18220 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f  lution are.** no
18230 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  t. ^Changes to a
18240 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
18250 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e  ntercepted by IN
18260 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
18270 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  s .** are not co
18280 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65  unted..** .** Se
18290 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
182a0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
182b0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
182c0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
182d0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
182e0 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
182f0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
18300 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
18310 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
18320 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
18330 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
18340 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
18350 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
18360 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
18370 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
18380 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
18390 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
183a0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
183b0 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
183c0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
183d0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
183e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
183f0 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
18400 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
18410 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
18420 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
18430 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
18440 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
18450 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
18460 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
18470 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
18480 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
18490 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
184a0 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
184b0 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
184c0 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
184d0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
184e0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
184f0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
18500 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
18510 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
18520 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
18530 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
18540 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
18550 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
18560 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
18570 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
18580 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
18590 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
185a0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
185b0 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
185c0 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
185d0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
185e0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
185f0 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
18600 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
18610 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
18620 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18630 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
18640 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
18650 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
18660 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
18670 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
18680 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
18690 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
186a0 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
186b0 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
186c0 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
186d0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
186e0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
186f0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
18700 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
18710 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
18720 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
18730 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
18740 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
18750 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
18760 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
18770 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
18780 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
18790 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
187a0 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
187b0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
187c0 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
187d0 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
187e0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
187f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
18800 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18810 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
18820 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
18830 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
18840 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
18850 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
18860 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
18870 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
18880 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
18890 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
188a0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
188b0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
188c0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
188d0 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
188e0 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
188f0 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
18900 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
18910 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
18920 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
18930 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
18940 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
18950 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
18960 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
18970 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
18980 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
18990 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
189a0 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
189b0 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
189c0 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
189d0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
189e0 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
189f0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
18a00 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
18a10 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
18a20 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
18a30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
18a40 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
18a50 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
18a60 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
18a70 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
18a80 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
18a90 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
18aa0 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  call returns..**
18ab0 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
18ac0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
18ad0 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c  loses while [sql
18ae0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18af0 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20  ].** is running 
18b00 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20  then bad things 
18b10 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70  will likely happ
18b20 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  en..*/.void sqli
18b30 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
18b40 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
18b50 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
18b60 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
18b70 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
18b80 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
18b90 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
18ba0 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
18bb0 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
18bc0 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
18bd0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
18be0 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
18bf0 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
18c00 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
18c10 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
18c20 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
18c30 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
18c40 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
18c50 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
18c60 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
18c70 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
18c80 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
18c90 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
18ca0 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
18cb0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
18cc0 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
18cd0 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
18ce0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
18cf0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
18d00 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
18d10 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
18d20 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
18d30 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
18d40 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
18d50 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
18d60 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
18d70 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
18d80 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
18d90 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
18da0 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
18db0 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
18dc0 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
18dd0 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
18de0 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
18df0 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
18e00 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
18e10 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
18e20 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
18e30 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
18e40 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
18e50 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
18e60 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
18e70 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
18e80 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
18e90 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
18ea0 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
18eb0 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
18ec0 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
18ed0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
18ee0 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
18ef0 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
18f00 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
18f10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
18f20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
18f30 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
18f40 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
18f50 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
18f60 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
18f70 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
18f80 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
18f90 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
18fa0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
18fb0 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
18fc0 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
18fd0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18fe0 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
18ff0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
19000 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
19010 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
19020 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
19030 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
19040 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
19050 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
19060 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
19070 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
19080 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
19090 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
190a0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
190b0 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
190c0 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
190d0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
190e0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
190f0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
19100 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
19110 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
19120 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
19130 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
19140 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
19150 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
19160 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
19170 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
19180 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
19190 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
191a0 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
191b0 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
191c0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
191d0 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
191e0 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
191f0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
19200 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
19210 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
19220 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  Errors.**.** ^Th
19230 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
19240 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f  andler(D,X,P) ro
19250 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
19260 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
19270 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62  .** that might b
19280 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  e invoked with a
19290 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76  rgument P whenev
192a0 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
192b0 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
192c0 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61  ss a database ta
192d0 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77  ble associated w
192e0 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ith.** [database
192f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77   connection] D w
19300 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hen another thre
19310 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
19320 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c   has the table l
19330 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71  ocked..** The sq
19340 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
19350 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  er() interface i
19360 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
19370 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ent.** [sqlite3_
19380 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
19390 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79  and [PRAGMA busy
193a0 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a  _timeout]..**.**
193b0 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
193c0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
193d0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
193e0 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  Y].** is returne
193f0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
19400 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
19410 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74  the lock.  ^If t
19420 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
19430 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
19440 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
19450 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  ck might be invo
19460 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
19470 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  uments..**.** ^T
19480 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
19490 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61  t to the busy ha
194a0 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
194b0 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
194c0 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
194d0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
194e0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
194f0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
19500 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
19510 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62  ment to.** the b
19520 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
19530 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
19540 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
19550 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19560 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
19570 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 73 61  voked for the sa
19580 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  me locking event
19590 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
195a0 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
195b0 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
195c0 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
195d0 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
195e0 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
195f0 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
19600 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72  E_BUSY] is retur
19610 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  ned.** to the ap
19620 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  plication..** ^I
19630 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
19640 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
19650 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
19660 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
19670 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
19680 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20  atabase and the 
19690 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
196a0 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
196b0 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
196c0 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
196d0 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
196e0 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
196f0 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
19700 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
19710 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
19720 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
19730 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
19740 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
19750 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
19760 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
19770 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
19780 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
19790 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
197a0 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20  tion instead of 
197b0 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a  invoking the .**
197c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
197d0 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
197e0 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
197f0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
19800 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
19810 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
19820 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
19830 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
19840 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
19850 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
19860 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
19870 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
19880 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
19890 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
198a0 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
198b0 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
198c0 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
198d0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
198e0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
198f0 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
19900 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
19910 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
19920 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
19930 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
19940 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
19950 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
19960 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
19970 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
19980 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
19990 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
199a0 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
199b0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
199c0 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
199d0 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
199e0 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
199f0 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
19a00 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
19a10 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
19a20 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
19a30 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
19a40 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
19a50 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
19a60 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
19a70 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ULL..**.** ^(The
19a80 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
19a90 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
19aa0 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
19ab0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
19ac0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
19ad0 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
19ae0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
19af0 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
19b00 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
19b10 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
19b20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
19b30 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
19b40 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  .** or evaluatin
19b50 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  g [PRAGMA busy_t
19b60 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63  imeout=N] will c
19b70 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73  hange the.** bus
19b80 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68  y handler and th
19b90 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65  us clear any pre
19ba0 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79  viously set busy
19bb0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
19bc0 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
19bd0 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
19be0 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
19bf0 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
19c00 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
19c10 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
19c20 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
19c30 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ler.  In other w
19c40 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73  ords,.** the bus
19c50 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74  y handler is not
19c60 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79   reentrant.  Any
19c70 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
19c80 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
19c90 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
19ca0 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
19cb0 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
19cc0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
19cd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
19ce0 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
19cf0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
19d00 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
19d10 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
19d20 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
19d30 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
19d40 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
19d50 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
19d60 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
19d70 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a  sy Timeout.**.**
19d80 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
19d90 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
19da0 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
19db0 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
19dc0 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
19dd0 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
19de0 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
19df0 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
19e00 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
19e10 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
19e20 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
19e30 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
19e40 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
19e50 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
19e60 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
19e70 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
19e80 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
19e90 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
19ea0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
19eb0 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
19ec0 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
19ed0 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
19ee0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
19ef0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
19f00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
19f10 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
19f20 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
19f30 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
19f40 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
19f50 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
19f60 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
19f70 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
19f80 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
19f90 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
19fa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19fb0 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e  on] at any given
19fc0 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
19fd0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
19fe0 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
19ff0 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
1a000 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1a010 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
1a020 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
1a030 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
1a040 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1a050 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  cleared.)^.**.**
1a060 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41   See also:  [PRA
1a070 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1a080 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1a090 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
1a0a0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
1a0b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a0c0 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
1a0d0 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
1a0e0 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
1a0f0 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
1a100 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
1a110 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
1a120 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1a130 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
1a140 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
1a150 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
1a160 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
1a170 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
1a180 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
1a190 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
1a1a0 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
1a1b0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
1a1c0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1a1d0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
1a1e0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
1a1f0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
1a200 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
1a210 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
1a220 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
1a230 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
1a240 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
1a250 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
1a260 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
1a270 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
1a280 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
1a290 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1a2a0 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
1a2b0 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
1a2c0 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
1a2d0 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
1a2e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1a2f0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
1a300 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1a310 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
1a320 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
1a330 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
1a340 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
1a350 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1a360 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
1a370 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
1a380 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
1a390 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
1a3a0 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
1a3b0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1a3c0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
1a3d0 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
1a3e0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1a3f0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
1a400 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
1a410 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
1a420 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
1a430 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
1a440 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
1a450 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
1a460 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
1a470 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1a480 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
1a490 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
1a4a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1a4b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1a4c0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
1a4d0 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
1a4e0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
1a4f0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
1a500 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
1a510 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1a520 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
1a530 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
1a540 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1a550 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
1a560 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
1a570 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
1a580 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1a590 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
1a5a0 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
1a5b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1a5c0 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
1a5d0 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
1a5e0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
1a5f0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1a600 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1a610 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
1a620 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
1a630 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
1a640 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
1a650 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
1a660 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
1a670 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
1a680 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
1a690 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
1a6a0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1a6b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
1a6c0 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
1a6d0 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
1a6e0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
1a6f0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
1a700 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
1a710 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
1a720 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1a730 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
1a740 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
1a750 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
1a760 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
1a770 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
1a780 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1a790 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
1a7a0 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
1a7b0 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
1a7c0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
1a7d0 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
1a7e0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a7f0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
1a800 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a810 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
1a820 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a830 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
1a840 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a850 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
1a860 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
1a870 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
1a880 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
1a890 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1a8a0 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
1a8b0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1a8c0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1a8d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a8e0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
1a8f0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
1a900 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
1a910 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
1a920 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1a930 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1a940 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1a950 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1a960 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1a970 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1a980 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1a990 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1a9a0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1a9b0 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1a9c0 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1a9d0 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1a9e0 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1a9f0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1aa00 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1aa10 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1aa20 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1aa30 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1aa40 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1aa50 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1aa60 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1aa70 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1aa80 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1aa90 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1aaa0 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1aab0 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1aac0 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1aad0 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1aae0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1aaf0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1ab00 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1ab10 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1ab20 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1ab30 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1ab40 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1ab50 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1ab60 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1ab70 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1ab80 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1ab90 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1aba0 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1abb0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1abc0 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1abd0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1abe0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1abf0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1ac00 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1ac10 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1ac20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1ac30 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1ac40 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1ac50 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1ac60 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1ac70 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1ac80 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1ac90 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1aca0 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1acb0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1acc0 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1acd0 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1ace0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1acf0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1ad00 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1ad10 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1ad20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1ad30 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
1ad40 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1ad50 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
1ad60 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
1ad70 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1ad80 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
1ad90 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
1ada0 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
1adb0 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
1adc0 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
1add0 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
1ade0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1adf0 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
1ae00 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1ae10 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
1ae20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1ae30 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
1ae40 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
1ae50 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
1ae60 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
1ae70 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
1ae80 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
1ae90 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1aea0 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
1aeb0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1aec0 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
1aed0 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
1aee0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1aef0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1af00 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
1af10 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
1af20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1af30 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
1af40 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1af50 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ry..**.** ^The s
1af60 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1af70 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
1af80 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
1af90 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
1afa0 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
1afb0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
1afc0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
1afd0 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
1afe0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1aff0 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
1b000 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
1b010 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
1b020 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
1b030 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
1b040 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
1b050 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
1b060 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
1b070 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1b080 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
1b090 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1b0a0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
1b0b0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
1b0c0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1b0d0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
1b0e0 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
1b0f0 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
1b100 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1b110 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
1b120 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
1b130 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
1b140 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
1b150 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1b160 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
1b170 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
1b180 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
1b190 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
1b1a0 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
1b1b0 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
1b1c0 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
1b1d0 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
1b1e0 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
1b1f0 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
1b200 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
1b210 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
1b220 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
1b230 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1b240 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
1b250 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
1b260 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
1b270 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1b280 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
1b290 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
1b2a0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
1b2b0 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
1b2c0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
1b2d0 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
1b2e0 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
1b2f0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1b300 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
1b310 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
1b320 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
1b330 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
1b340 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
1b350 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
1b360 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1b370 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
1b380 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
1b390 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
1b3a0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
1b3b0 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
1b3c0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
1b3d0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1b3e0 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
1b3f0 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
1b400 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
1b410 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
1b420 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1b430 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
1b440 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
1b450 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
1b460 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
1b470 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
1b480 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
1b490 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
1b4a0 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
1b4b0 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
1b4c0 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
1b4d0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
1b4e0 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
1b4f0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1b500 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
1b510 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1b520 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
1b530 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1b540 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
1b550 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
1b560 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
1b570 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
1b580 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
1b590 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
1b5a0 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
1b5b0 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
1b5c0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1b5d0 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
1b5e0 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
1b5f0 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
1b600 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
1b610 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1b620 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1b630 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1b640 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1b650 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1b660 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1b670 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1b680 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1b690 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1b6a0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1b6b0 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1b6c0 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1b6d0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1b6e0 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1b6f0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1b700 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1b710 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1b720 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1b730 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1b740 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1b750 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1b760 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1b770 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1b780 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1b790 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1b7a0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1b7b0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1b7c0 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1b7d0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1b7e0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b7f0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1b800 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1b810 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1b820 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1b830 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1b840 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b850 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1b860 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1b870 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1b880 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1b890 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1b8a0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1b8b0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1b8c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1b8d0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1b8e0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1b8f0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1b900 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1b910 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1b920 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1b930 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1b940 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1b950 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1b960 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1b970 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1b980 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1b990 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1b9a0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1b9b0 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1b9c0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1b9d0 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1b9e0 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1b9f0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1ba00 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1ba10 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1ba20 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1ba30 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1ba40 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1ba50 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1ba60 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1ba70 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1ba80 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1ba90 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1baa0 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1bab0 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1bac0 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1bad0 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1bae0 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1baf0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1bb00 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1bb10 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1bb20 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1bb30 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1bb40 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1bb50 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1bb60 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1bb70 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1bb80 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1bb90 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1bba0 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1bbb0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1bbc0 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1bbd0 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1bbe0 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1bbf0 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1bc00 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1bc10 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1bc20 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1bc30 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1bc40 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1bc50 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1bc60 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1bc70 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1bc80 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1bc90 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1bca0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1bcb0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1bcc0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1bcd0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1bce0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1bcf0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1bd00 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1bd10 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1bd20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1bd30 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1bd40 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1bd50 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1bd60 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1bd70 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1bd80 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
1bd90 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
1bda0 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
1bdb0 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
1bdc0 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
1bdd0 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
1bde0 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
1bdf0 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
1be00 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
1be10 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
1be20 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
1be30 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
1be40 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
1be50 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1be60 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
1be70 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
1be80 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1be90 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
1bea0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
1beb0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1bec0 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  r*, ...);.char *
1bed0 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1bee0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1bef0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1bf00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1bf10 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1bf20 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
1bf30 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
1bf40 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
1bf50 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
1bf60 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
1bf70 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
1bf80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1bf90 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
1bfa0 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
1bfb0 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
1bfc0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
1bfd0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
1bfe0 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
1bff0 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
1c000 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
1c010 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
1c020 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
1c030 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
1c040 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1c050 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1c060 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
1c070 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
1c080 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
1c090 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1c0a0 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
1c0b0 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
1c0c0 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71  meter..** ^If sq
1c0d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1c0e0 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
1c0f0 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
1c100 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
1c110 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1c120 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68  pointer.  ^If th
1c130 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
1c140 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1c150 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
1c160 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
1c170 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1c180 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
1c190 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1c1a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
1c1b0 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65  loc64(N) routine
1c1c0 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65   works just like
1c1d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1c1e0 6f 63 28 4e 29 20 65 78 63 65 70 74 20 74 68 61  oc(N) except tha
1c1f0 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e  t N is an unsign
1c200 65 64 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  ed 64-bit intege
1c210 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  r instead.** of 
1c220 61 20 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20  a signed 32-bit 
1c230 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  integer..**.** ^
1c240 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
1c250 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
1c260 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
1c270 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1c280 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c290 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1c2a0 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
1c2b0 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
1c2c0 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
1c2d0 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20  e reused.  ^The 
1c2e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
1c2f0 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
1c300 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
1c310 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
1c320 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
1c330 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
1c340 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
1c350 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
1c360 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
1c370 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
1c380 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
1c390 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
1c3a0 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
1c3b0 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
1c3c0 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
1c3d0 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
1c3e0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1c3f0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1c400 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
1c410 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
1c420 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1c430 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
1c440 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
1c450 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
1c460 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
1c470 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
1c480 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
1c490 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
1c4a0 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
1c4b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1c4c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c4d0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
1c4e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1c4f0 4e 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  N) interface att
1c500 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20  empts to resize 
1c510 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72  a.** prior memor
1c520 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74  y allocation X t
1c530 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
1c540 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
1c550 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e X parameter to
1c560 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c570 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55  (X,N).** is a NU
1c580 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
1c590 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
1c5a0 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
1c5b0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1c5c0 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49  malloc(N)..** ^I
1c5d0 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  f the N paramete
1c5e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1c5f0 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72  lloc(X,N) is zer
1c600 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65  o or.** negative
1c610 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1c620 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68  or is exactly th
1c630 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e  e same as callin
1c640 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65  g.** sqlite3_fre
1c650 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65  e(X)..** ^sqlite
1c660 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72  3_realloc(X,N) r
1c670 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1c680 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
1c690 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
1c6a0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1c6b0 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
1c6c0 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d  f insufficient m
1c6d0 65 6d 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62  emory is availab
1c6e0 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20  le..** ^If M is 
1c6f0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
1c700 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1c710 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
1c720 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
1c730 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1c740 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
1c750 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1c760 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
1c770 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1c780 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64  realloc(X,N) and
1c790 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1c7a0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
1c7b0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
1c7c0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
1c7d0 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69  rns NULL and N i
1c7e0 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e  s positive, then
1c7f0 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c   the.** prior al
1c800 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  location is not 
1c810 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
1c820 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1c830 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61  c64(X,N) interfa
1c840 63 65 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61  ces works the sa
1c850 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33  me as.** sqlite3
1c860 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78  _realloc(X,N) ex
1c870 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61  cept that N is a
1c880 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   64-bit unsigned
1c890 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64   integer instead
1c8a0 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20  .** of a 32-bit 
1c8b0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a  signed integer..
1c8c0 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61  **.** ^If X is a
1c8d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1c8e0 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  on previously ob
1c8f0 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
1c900 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  te3_malloc(),.**
1c910 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1c920 34 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61  4(), sqlite3_rea
1c930 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74  lloc(), or sqlit
1c940 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20  e3_realloc64(), 
1c950 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
1c960 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73  msize(X) returns
1c970 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61   the size of tha
1c980 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
1c990 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a  ion in bytes..**
1c9a0 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
1c9b0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1c9c0 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62  msize(X) might b
1c9d0 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
1c9e0 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62  e number.** of b
1c9f0 79 74 65 73 20 72 65 71 75 65 73 74 65 64 20 77  ytes requested w
1ca00 68 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61  hen X was alloca
1ca10 74 65 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61  ted.  ^If X is a
1ca20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1ca30 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
1ca40 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a  ize(X) returns z
1ca50 65 72 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74  ero.  If X point
1ca60 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74  s to something t
1ca70 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68  hat is not.** th
1ca80 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d  e beginning of m
1ca90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1caa0 2c 20 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74  , or if it point
1cab0 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a  s to a formerly.
1cac0 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20  ** valid memory 
1cad0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20  allocation that 
1cae0 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65  has now been fre
1caf0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ed, then the beh
1cb00 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69  avior.** of sqli
1cb10 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20  te3_msize(X) is 
1cb20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f  undefined and po
1cb30 73 73 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  ssibly harmful..
1cb40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
1cb50 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  y returned by sq
1cb60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20  lite3_malloc(), 
1cb70 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1cb80 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ),.** sqlite3_ma
1cb90 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71  lloc64(), and sq
1cba0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1cbb0 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
1cbc0 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
1cbd0 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
1cbe0 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a  ndary, or to a.*
1cbf0 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72  * 4 byte boundar
1cc00 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  y if the [SQLITE
1cc10 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f  _4_BYTE_ALIGNED_
1cc20 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d  MALLOC] compile-
1cc30 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69  time.** option i
1cc40 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  s used..**.** In
1cc50 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1cc60 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
1cc70 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
1cc80 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
1cc90 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
1cca0 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
1ccb0 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
1ccc0 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
1ccd0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
1cce0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1ccf0 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
1cd00 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
1cd10 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
1cd20 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
1cd30 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
1cd40 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
1cd50 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n be used..**.**
1cd60 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65   Prior to SQLite
1cd70 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c   version 3.7.10,
1cd80 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   the Windows OS 
1cd90 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
1cda0 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79  called.** the sy
1cdb0 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
1cdc0 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
1cdd0 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
1cde0 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
1cdf0 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
1ce00 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
1ce10 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
1ce20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
1ce30 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
1ce40 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
1ce50 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
1ce60 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
1ce70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1ce80 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74   errors were det
1ce90 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
1cea0 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64  ey were reported
1ceb0 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
1cec0 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
1ced0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
1cee0 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
1cef0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
1cf00 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72  * The pointer ar
1cf10 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
1cf20 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
1cf30 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1cf40 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65  ()].** must be e
1cf50 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c  ither NULL or el
1cf60 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61  se pointers obta
1cf70 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
1cf80 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20  r.** invocation 
1cf90 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1cfa0 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
1cfb0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61  3_realloc()] tha
1cfc0 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65  t have.** not ye
1cfd0 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e  t been released.
1cfe0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
1cff0 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
1d000 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e  read or write an
1d010 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62  y part of.** a b
1d020 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61  lock of memory a
1d030 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
1d040 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a   released using.
1d050 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1d060 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1d070 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76  realloc()]..*/.v
1d080 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
1d090 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  loc(int);.void *
1d0a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1d0b0 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  (sqlite3_uint64)
1d0c0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
1d0d0 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
1d0e0 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
1d0f0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69  e3_realloc64(voi
1d100 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  d*, sqlite3_uint
1d110 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
1d120 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73  3_free(void*);.s
1d130 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71  qlite3_uint64 sq
1d140 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64  lite3_msize(void
1d150 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1d160 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1d170 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
1d180 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
1d190 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
1d1a0 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
1d1b0 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
1d1c0 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
1d1d0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
1d1e0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
1d1f0 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
1d200 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1d210 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
1d220 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
1d230 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1d240 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
1d250 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
1d260 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1d270 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
1d280 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1d290 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d  of bytes.** of m
1d2a0 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
1d2b0 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
1d2c0 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
1d2d0 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  eed)..** ^The [s
1d2e0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1d2f0 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
1d300 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
1d310 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20  aximum.** value 
1d320 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
1d330 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65  ry_used()] since
1d340 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1d350 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74  mark.** was last
1d360 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61   reset.  ^The va
1d370 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
1d380 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1d390 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1d3a0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1d3b0 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
1d3c0 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
1d3d0 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51  d.** added by SQ
1d3e0 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
1d3f0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
1d400 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1d410 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65  ,.** but not ove
1d420 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
1d430 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
1d440 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
1d450 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
1d460 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
1d470 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
1d480 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1d490 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1d4a0 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
1d4b0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
1d4c0 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  f.** [sqlite3_me
1d4d0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
1d4e0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
1d4f0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
1d500 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1d510 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
1d520 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75  true.  ^The valu
1d530 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
1d540 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1d550 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
1d560 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
1d570 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74   mark.** prior t
1d580 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
1d590 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1d5a0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1d5b0 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33  d(void);.sqlite3
1d5c0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1d5d0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1d5e0 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a  int resetFlag);.
1d5f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d600 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e   Pseudo-Random N
1d610 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a  umber Generator.
1d620 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e  **.** SQLite con
1d630 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61  tains a high-qua
1d640 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64  lity pseudo-rand
1d650 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61  om number genera
1d660 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20  tor (PRNG) used 
1d670 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e  to.** select ran
1d680 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57  dom [ROWID | ROW
1d690 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74  IDs] when insert
1d6a0 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20  ing new records 
1d6b0 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61  into a table tha
1d6c0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65  t.** already use
1d6d0 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f  s the largest po
1d6e0 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20  ssible [ROWID]. 
1d6f0 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73   The PRNG is als
1d700 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68  o used for.** th
1d710 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f  e build-in rando
1d720 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c  m() and randombl
1d730 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  ob() SQL functio
1d740 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66  ns.  This interf
1d750 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70  ace allows.** ap
1d760 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63  plications to ac
1d770 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52  cess the same PR
1d780 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72  NG for other pur
1d790 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  poses..**.** ^A 
1d7a0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
1d7b0 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79  tine stores N by
1d7c0 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
1d7d0 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
1d7e0 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d  .** ^The P param
1d7f0 65 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55  eter can be a NU
1d800 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1d810 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69  * ^If this routi
1d820 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  ne has not been 
1d830 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65  previously calle
1d840 64 20 6f 72 20 69 66 20 74 68 65 20 70 72 65 76  d or if the prev
1d850 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64  ious.** call had
1d860 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65   N less than one
1d870 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
1d880 65 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74  er for P, then t
1d890 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65  he PRNG is.** se
1d8a0 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
1d8b0 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66  mness obtained f
1d8c0 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e  rom the xRandomn
1d8d0 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a  ess method of.**
1d8e0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1d8f0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1d900 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  t..** ^If the pr
1d910 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74  evious call to t
1d920 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20  his routine had 
1d930 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72  an N of 1 or mor
1d940 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e  e and a.** non-N
1d950 55 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70  ULL P then the p
1d960 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
1d970 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
1d980 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
1d990 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
1d9a0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1d9b0 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
1d9c0 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  s.** method..*/.
1d9d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
1d9e0 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
1d9f0 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
1da00 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
1da10 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
1da20 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
1da30 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1da40 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
1da50 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1da60 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
1da70 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1da80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
1da90 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
1daa0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
1dab0 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
1dac0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1dad0 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
1dae0 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
1daf0 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
1db00 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
1db10 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1db20 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
1db30 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
1db40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1db50 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
1db60 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1db70 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
1db80 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
1db90 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
1dba0 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
1dbb0 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
1dbc0 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
1dbd0 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
1dbe0 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
1dbf0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1dc00 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
1dc10 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
1dc20 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
1dc30 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1dc40 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1dc50 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1dc60 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
1dc70 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
1dc80 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
1dc90 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
1dca0 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
1dcb0 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
1dcc0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
1dcd0 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
1dce0 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
1dcf0 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
1dd00 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
1dd10 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1dd20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
1dd30 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
1dd40 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
1dd50 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
1dd60 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
1dd70 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
1dd80 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
1dd90 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
1dda0 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
1ddb0 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
1ddc0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1ddd0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1dde0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
1ddf0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1de00 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1de10 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1de20 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
1de30 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1de40 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
1de50 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
1de60 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
1de70 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
1de80 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1de90 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1dea0 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
1deb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1dec0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1ded0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1dee0 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
1def0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1df00 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1df10 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
1df20 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
1df30 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
1df40 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1df50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1df60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1df70 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
1df80 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
1df90 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1dfa0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1dfb0 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
1dfc0 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
1dfd0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
1dfe0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1dff0 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
1e000 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
1e010 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
1e020 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
1e030 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
1e040 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1e050 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
1e060 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
1e070 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
1e080 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
1e090 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1e0a0 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
1e0b0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
1e0c0 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
1e0d0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1e0e0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
1e0f0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1e100 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
1e110 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
1e120 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1e130 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1e140 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
1e150 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e160 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
1e170 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
1e180 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
1e190 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
1e1a0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
1e1b0 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
1e1c0 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
1e1d0 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
1e1e0 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
1e1f0 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
1e200 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
1e210 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
1e220 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
1e230 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
1e240 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
1e250 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
1e260 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  able..** ^If the
1e270 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1e280 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
1e290 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1e2a0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
1e2b0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1e2c0 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
1e2d0 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
1e2e0 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
1e2f0 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
1e300 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
1e310 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
1e320 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
1e330 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
1e340 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
1e350 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
1e360 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1e370 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
1e380 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
1e390 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1e3a0 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
1e3b0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1e3c0 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
1e3d0 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
1e3e0 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
1e3f0 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
1e400 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
1e410 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
1e420 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
1e430 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
1e440 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
1e450 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
1e460 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
1e470 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
1e480 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
1e490 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
1e4a0 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
1e4b0 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
1e4c0 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
1e4d0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
1e4e0 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
1e4f0 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
1e500 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
1e510 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
1e520 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
1e530 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
1e540 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
1e550 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
1e560 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
1e570 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
1e580 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1e590 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
1e5a0 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
1e5b0 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
1e5c0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1e5d0 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
1e5e0 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
1e5f0 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
1e600 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
1e610 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
1e620 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
1e630 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
1e640 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
1e650 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
1e660 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
1e670 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
1e680 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
1e690 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
1e6a0 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
1e6b0 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
1e6c0 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
1e6d0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
1e6e0 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
1e6f0 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
1e700 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e710 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
1e720 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
1e730 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1e740 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
1e750 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
1e760 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
1e770 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
1e780 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
1e790 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
1e7a0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1e7b0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
1e7c0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
1e7d0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1e7e0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1e7f0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1e800 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1e810 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1e820 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1e830 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
1e840 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
1e850 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
1e860 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1e870 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
1e880 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
1e890 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
1e8a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1e8b0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
1e8c0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
1e8d0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
1e8e0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
1e8f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1e900 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
1e910 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1e920 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
1e930 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
1e940 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
1e950 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1e960 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
1e970 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
1e980 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
1e990 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
1e9a0 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
1e9b0 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
1e9c0 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
1e9d0 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
1e9e0 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
1e9f0 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
1ea00 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
1ea10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ea20 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
1ea30 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
1ea40 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1ea50 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
1ea60 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
1ea70 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
1ea80 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
1ea90 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
1eaa0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
1eab0 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
1eac0 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
1ead0 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
1eae0 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
1eaf0 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
1eb00 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1eb10 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
1eb20 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
1eb30 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
1eb40 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1eb50 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1eb60 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
1eb70 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
1eb80 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
1eb90 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1eba0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1ebb0 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
1ebc0 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
1ebd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1ebe0 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
1ebf0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1ec00 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1ec10 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1ec20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
1ec30 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
1ec40 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
1ec50 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
1ec60 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
1ec70 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
1ec80 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
1ec90 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
1eca0 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
1ecb0 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
1ecc0 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
1ecd0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1ece0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
1ecf0 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
1ed00 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1ed10 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1ed20 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
1ed30 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
1ed40 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e  o used as a [con
1ed50 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e  flict resolution
1ed60 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e   mode].** return
1ed70 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  ed from the [sql
1ed80 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
1ed90 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61  flict()] interfa
1eda0 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
1edb0 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
1edc0 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
1edd0 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
1ede0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
1edf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
1ee00 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
1ee10 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
1ee20 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
1ee30 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
1ee40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1ee50 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
1ee60 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1ee70 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1ee80 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
1ee90 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
1eea0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1eeb0 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
1eec0 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
1eed0 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
1eee0 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
1eef0 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
1ef00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1ef10 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1ef20 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
1ef30 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1ef40 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
1ef50 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
1ef60 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
1ef70 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
1ef80 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
1ef90 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1efa0 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
1efb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
1efc0 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
1efd0 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
1efe0 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
1eff0 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
1f000 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
1f010 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
1f020 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
1f030 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
1f040 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1f050 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
1f060 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
1f070 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
1f080 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
1f090 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
1f0a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
1f0b0 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
1f0c0 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
1f0d0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1f0e0 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
1f0f0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1f100 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
1f110 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
1f120 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
1f130 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
1f140 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1f150 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1f160 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1f170 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
1f180 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
1f190 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
1f1a0 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
1f1b0 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
1f1c0 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
1f1d0 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
1f1e0 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
1f1f0 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
1f200 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
1f210 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f220 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
1f230 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
1f240 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
1f250 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f260 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
1f270 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
1f280 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1f290 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f2a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f2b0 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
1f2c0 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
1f2d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1f2e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f2f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1f300 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
1f310 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
1f320 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1f330 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1f340 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1f350 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
1f360 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
1f370 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f380 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f390 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1f3a0 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
1f3b0 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
1f3c0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1f3d0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1f3e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1f3f0 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
1f400 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
1f410 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1f420 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f430 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1f440 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
1f450 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
1f460 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1f470 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f480 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1f490 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1f4a0 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
1f4b0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f4c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f4d0 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
1f4e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
1f4f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1f500 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f510 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f520 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
1f530 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
1f540 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1f550 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1f560 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f570 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
1f580 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
1f590 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f5a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f5b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f5c0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1f5d0 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
1f5e0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1f5f0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1f600 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f610 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
1f620 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
1f630 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f640 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f650 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f660 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
1f670 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
1f680 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1f690 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f6a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f6b0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
1f6c0 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
1f6d0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1f6e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f6f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f700 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
1f710 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
1f720 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1f730 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f740 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f750 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
1f760 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
1f770 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1f780 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f790 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f7a0 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
1f7b0 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
1f7c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1f7d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f7e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
1f7f0 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
1f800 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
1f810 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
1f820 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
1f830 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1f840 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
1f850 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
1f860 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
1f870 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
1f880 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
1f890 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
1f8a0 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
1f8b0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
1f8c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f8d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
1f8e0 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
1f8f0 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
1f900 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
1f910 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f920 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
1f930 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
1f940 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
1f950 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1f960 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1f970 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
1f980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1f990 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
1f9a0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f9b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f9c0 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
1f9d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
1f9e0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
1f9f0 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
1fa00 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1fa10 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
1fa20 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
1fa30 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
1fa40 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
1fa50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1fa60 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
1fa70 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
1fa80 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1fa90 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1faa0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1fab0 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
1fac0 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
1fad0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1fae0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1faf0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1fb00 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
1fb10 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
1fb20 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1fb30 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
1fb40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1fb50 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
1fb60 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
1fb70 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1fb80 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
1fb90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fba0 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
1fbb0 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
1fbc0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1fbd0 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
1fbe0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fbf0 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
1fc00 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
1fc10 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
1fc20 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
1fc30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fc40 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
1fc50 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
1fc60 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
1fc70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1fc80 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20  ECURSIVE        
1fc90 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c      33   /* NULL
1fca0 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
1fcb0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a              */..
1fcc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1fcd0 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
1fce0 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
1fcf0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1fd00 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
1fd10 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
1fd20 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
1fd30 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
1fd40 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
1fd50 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
1fd60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1fd70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1fd80 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1fd90 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1fda0 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
1fdb0 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
1fdc0 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
1fdd0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1fde0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
1fdf0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1fe00 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
1fe10 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1fe20 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
1fe30 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
1fe40 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
1fe50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1fe60 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
1fe70 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
1fe80 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
1fe90 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
1fea0 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
1feb0 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
1fec0 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
1fed0 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
1fee0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
1fef0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
1ff00 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
1ff10 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
1ff20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
1ff30 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
1ff40 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ger.)^.**.** The
1ff50 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53   [SQLITE_TRACE_S
1ff60 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  IZE_LIMIT] compi
1ff70 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63  le-time option c
1ff80 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69  an be used to li
1ff90 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74  mit.** the lengt
1ffa0 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61  h of [bound para
1ffb0 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e  meter] expansion
1ffc0 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f   in the output o
1ffd0 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  f sqlite3_trace(
1ffe0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )..**.** ^The ca
1fff0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
20000 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
20010 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
20020 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
20030 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
20040 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
20050 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
20060 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
20070 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
20080 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
20090 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
200a0 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
200b0 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
200c0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
200d0 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
200e0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
200f0 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
20100 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
20110 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
20120 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
20130 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
20140 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
20150 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
20160 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
20170 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
20180 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
20190 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
201a0 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
201b0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
201c0 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
201d0 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
201e0 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
201f0 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
20200 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  k.  The.** sqlit
20210 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e  e3_profile() fun
20220 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ction is conside
20230 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
20240 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65   and is.** subje
20250 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
20260 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
20270 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f  of SQLite..*/.vo
20280 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
20290 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
202a0 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
202b0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
202c0 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50  id*);.SQLITE_EXP
202d0 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
202e0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
202f0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
20300 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
20310 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
20320 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
20330 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
20340 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
20350 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
20360 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
20370 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
20380 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
20390 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
203a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
203b0 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
203c0 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
203d0 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
203e0 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
203f0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
20400 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
20410 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
20420 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
20430 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
20440 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
20450 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
20460 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
20470 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
20480 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
20490 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
204a0 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
204b0 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
204c0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
204d0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
204e0 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
204f0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
20500 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
20510 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70  eter N is the ap
20520 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72  proximate number
20530 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
20540 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
20550 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
20560 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
20570 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
20580 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
20590 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20  he callback X.  
205a0 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68  ^If N is less th
205b0 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20  an one then the 
205c0 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64  progress.** hand
205d0 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ler is disabled.
205e0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
205f0 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
20600 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
20610 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
20620 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
20630 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
20640 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
20650 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
20660 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
20670 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
20680 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
20690 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
206a0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
206b0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
206c0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
206d0 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
206e0 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
206f0 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
20700 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
20710 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
20720 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
20730 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
20740 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
20750 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
20760 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
20770 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
20780 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
20790 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
207a0 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
207b0 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
207c0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
207d0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
207e0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
207f0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
20800 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20810 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
20820 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
20830 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
20840 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
20850 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
20860 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
20870 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
20880 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
20890 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
208a0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
208b0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
208c0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
208d0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
208e0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
208f0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
20900 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
20910 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
20920 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
20930 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
20940 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
20950 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
20960 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
20970 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
20980 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
20990 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
209a0 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
209b0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
209c0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
209d0 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
209e0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
209f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20a00 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
20a10 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
20a20 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
20a30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
20a40 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
20a50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
20a60 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
20a70 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
20a80 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
20a90 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
20aa0 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
20ab0 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
20ac0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
20ad0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
20ae0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
20af0 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
20b00 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
20b10 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
20b20 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
20b30 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
20b40 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
20b50 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
20b60 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
20b70 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
20b80 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
20b90 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
20ba0 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
20bb0 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
20bc0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
20bd0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
20be0 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
20bf0 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
20c00 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
20c10 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
20c20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
20c30 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
20c40 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
20c50 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
20c60 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
20c70 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
20c80 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
20c90 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
20ca0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
20cb0 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c  lt encoding will
20cc0 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61   be UTF-8 for da
20cd0 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20  tabases created 
20ce0 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  using.** sqlite3
20cf0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
20d00 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e  e3_open_v2().  ^
20d10 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
20d20 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73  ding for databas
20d30 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73  es.** created us
20d40 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
20d50 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46  16() will be UTF
20d60 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
20d70 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
20d80 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
20d90 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
20da0 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
20db0 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
20dc0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
20dd0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
20de0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
20df0 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
20e00 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
20e10 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
20e20 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
20e30 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
20e40 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
20e50 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
20e60 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
20e70 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
20e80 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
20e90 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
20ea0 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
20eb0 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
20ec0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
20ed0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
20ee0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
20ef0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
20f00 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
20f10 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
20f20 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
20f30 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
20f40 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
20f50 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
20f60 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
20f70 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
20f80 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
20f90 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
20fa0 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
20fb0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
20fc0 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
20fd0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
20fe0 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
20ff0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
21000 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
21010 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
21020 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
21030 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
21040 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
21050 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
21060 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
21070 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
21080 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
21090 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
210a0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
210b0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
210c0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
210d0 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
210e0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
210f0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
21100 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
21110 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
21120 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
21130 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
21140 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
21150 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
21160 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
21170 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
21180 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
21190 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
211a0 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
211b0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
211c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
211d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
211e0 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
211f0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
21200 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
21210 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
21220 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
21230 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
21240 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
21250 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
21260 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
21270 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
21280 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
21290 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
212a0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
212b0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
212c0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
212d0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
212e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
212f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
21300 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
21310 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
21320 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
21330 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
21340 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
21350 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
21360 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
21370 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
21380 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
21390 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
213a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
213b0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
213c0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
213d0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
213e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
213f0 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
21400 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
21410 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
21420 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
21430 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
21440 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
21450 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
21460 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
21470 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
21480 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
21490 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
214a0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
214b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
214c0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
214d0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
214e0 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
214f0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
21500 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
21510 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
21520 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
21530 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
21540 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
21550 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
21560 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
21570 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
21580 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
21590 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
215a0 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
215b0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
215c0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
215d0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
215e0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
215f0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
21600 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
21610 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
21620 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
21630 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
21640 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21650 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
21660 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
21670 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
21680 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
21690 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
216a0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
216b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
216c0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
216d0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
216e0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
216f0 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
21700 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
21710 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
21720 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
21730 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21740 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
21750 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
21760 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
21770 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
21780 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
21790 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
217a0 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
217b0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
217c0 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
217d0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
217e0 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
217f0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
21800 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
21810 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
21820 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
21830 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
21840 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
21850 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21860 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
21870 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
21880 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
21890 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
218a0 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
218b0 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
218c0 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
218d0 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
218e0 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
218f0 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
21900 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
21910 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
21920 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
21930 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
21940 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
21950 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
21960 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
21970 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
21980 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
21990 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
219a0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
219b0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
219c0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
219d0 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
219e0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
219f0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
21a00 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
21a10 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
21a20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
21a30 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
21a40 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
21a50 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
21a60 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
21a70 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
21a80 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
21a90 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
21aa0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
21ab0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
21ac0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
21ad0 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
21ae0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
21af0 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
21b00 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
21b10 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
21b20 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
21b30 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
21b40 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
21b50 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
21b60 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
21b70 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
21b80 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
21b90 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
21ba0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
21bb0 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
21bc0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
21bd0 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
21be0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
21bf0 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
21c00 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
21c10 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
21c20 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
21c30 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
21c40 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
21c50 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
21c60 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
21c70 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
21c80 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
21c90 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
21ca0 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
21cb0 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
21cc0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
21cd0 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
21ce0 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
21cf0 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
21d00 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
21d10 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
21d20 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
21d30 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
21d40 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
21d50 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
21d60 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
21d70 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
21d80 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
21d90 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
21da0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
21db0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
21dc0 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
21dd0 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
21de0 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
21df0 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
21e00 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
21e10 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
21e20 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
21e30 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
21e40 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
21e50 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
21e60 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
21e70 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
21e80 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
21e90 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
21ea0 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
21eb0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
21ec0 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
21ed0 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
21ee0 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
21ef0 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
21f00 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
21f10 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
21f20 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
21f30 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
21f40 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
21f50 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
21f60 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
21f70 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
21f80 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
21f90 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
21fa0 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
21fb0 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
21fc0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
21fd0 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
21fe0 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77   .** ^(On window
21ff0 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
22000 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
22010 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
22020 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
22030 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
22040 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  :").)^.**.** [[c
22050 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
22060 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
22070 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
22080 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
22090 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
220a0 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
220b0 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
220c0 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
220d0 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
220e0 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
220f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
22100 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20   SQLite and its 
22110 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d  built-in [VFSes]
22120 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
22130 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72  * following quer
22140 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
22150 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
22160 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
22170 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
22180 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
22190 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
221a0 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
221b0 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
221c0 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
221d0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
221e0 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
221f0 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
22200 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
22210 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
22220 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
22230 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
22240 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
22250 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
22260 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
22270 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
22280 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
22290 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
222a0 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
222b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
222c0 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
222d0 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
222e0 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
222f0 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
22300 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
22310 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
22320 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
22330 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
22340 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
22350 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
22360 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
22370 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
22380 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
22390 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
223a0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
223b0 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
223c0 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
223d0 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
223e0 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
223f0 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
22400 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
22410 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
22420 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
22430 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
22440 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
22450 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
22460 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
22470 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
22480 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
22490 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
224a0 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
224b0 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
224c0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
224d0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74  open_v2(). ^If t
224e0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
224f0 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
22500 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
22510 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
22520 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
22530 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
22540 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
22550 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
22560 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
22570 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
22580 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
22590 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
225a0 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
225b0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
225c0 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
225d0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
225e0 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
225f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
22600 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
22610 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
22620 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
22630 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
22640 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
22650 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
22660 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
22670 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
22680 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
22690 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
226a0 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
226b0 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
226c0 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
226d0 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
226e0 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
226f0 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
22700 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
22710 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
22720 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
22730 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
22740 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
22750 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
22760 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
22770 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
22780 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
22790 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
227a0 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
227b0 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
227c0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
227d0 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
227e0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
227f0 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
22800 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
22810 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
22820 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22830 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
22840 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
22850 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
22860 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
22870 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
22880 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
22890 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
228a0 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
228b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
228c0 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
228d0 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
228e0 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
228f0 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
22900 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
22910 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
22920 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62  vior requested b
22930 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
22940 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
22950 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
22960 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
22970 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a  ACHE flag..**.**
22980 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f    <li> <b>psow</
22990 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61  b>: ^The psow pa
229a0 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65  rameter indicate
229b0 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  s whether or not
229c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77   the.**     [pow
229d0 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65  ersafe overwrite
229e0 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20  ] property does 
229f0 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c  or does not appl
22a00 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  y to the.**     
22a10 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e  storage media on
22a20 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62   which the datab
22a30 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73  ase file resides
22a40 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
22a50 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68  >nolock</b>: ^Th
22a60 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74  e nolock paramet
22a70 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
22a80 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a  query parameter.
22a90 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20  **     which if 
22aa0 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c  set disables fil
22ab0 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c  e locking in rol
22ac0 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f  lback journal mo
22ad0 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20  des.  This.**   
22ae0 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20    is useful for 
22af0 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61  accessing a data
22b00 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79  base on a filesy
22b10 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e  stem that does n
22b20 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72  ot.**     suppor
22b30 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74  t locking.  Caut
22b40 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63  ion:  Database c
22b50 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20  orruption might 
22b60 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a  result if two.**
22b70 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f       or more pro
22b80 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20  cesses write to 
22b90 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
22ba0 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66  e and any one of
22bb0 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72   those.**     pr
22bc0 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c  ocesses uses nol
22bd0 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  ock=1..**.**  <l
22be0 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c  i> <b>immutable<
22bf0 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61  /b>: ^The immuta
22c00 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ble parameter is
22c10 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
22c20 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65  .**     paramete
22c30 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  r that indicates
22c40 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
22c50 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65  se file is store
22c60 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64  d on.**     read
22c70 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57  -only media.  ^W
22c80 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73  hen immutable is
22c90 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73   set, SQLite ass
22ca0 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
22cb0 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69       database fi
22cc0 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  le cannot be cha
22cd0 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20  nged, even by a 
22ce0 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67  process with hig
22cf0 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69  her.**     privi
22d00 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  lege, and so the
22d10 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
22d20 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e  ned read-only an
22d30 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a  d all locking.**
22d40 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20       and change 
22d50 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73  detection is dis
22d60 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a  abled.  Caution:
22d70 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d   Setting the imm
22d80 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72  utable.**     pr
22d90 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61  operty on a data
22da0 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64  base file that d
22db0 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e  oes in fact chan
22dc0 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a  ge can result.**
22dd0 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63       in incorrec
22de0 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  t query results 
22df0 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43  and/or [SQLITE_C
22e00 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a  ORRUPT] errors..
22e10 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a  **     See also:
22e20 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
22e30 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20  MMUTABLE]..**   
22e40 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a      .** </ul>.**
22e50 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
22e60 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
22e70 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
22e80 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
22e90 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
22ea0 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
22eb0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
22ec0 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
22ed0 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
22ee0 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
22ef0 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
22f00 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
22f10 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
22f20 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
22f30 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
22f40 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
22f50 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
22f60 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
22f70 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
22f80 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
22f90 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
22fa0 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
22fb0 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
22fc0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
22fd0 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
22fe0 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
22ff0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
23000 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
23010 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
23020 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
23030 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
23040 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
23050 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
23060 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
23070 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
23080 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
23090 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
230a0 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
230b0 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
230c0 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
230d0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
230e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
230f0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
23100 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
23110 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
23120 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
23130 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
23140 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
23150 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
23160 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
23170 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
23180 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
23190 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
231a0 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
231b0 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
231c0 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
231d0 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
231e0 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
231f0 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
23200 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
23210 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
23220 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
23230 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
23240 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
23250 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
23260 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
23270 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
23280 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
23290 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
232a0 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
232b0 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
232c0 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
232d0 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
232e0 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
232f0 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
23300 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
23310 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
23320 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
23330 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
23340 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
23350 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
23360 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
23370 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
23380 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
23390 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
233a0 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
233b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
233c0 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
233d0 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
233e0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
233f0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
23400 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20  fs=unix-dotfile 
23410 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
23420 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
23430 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
23440 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
23450 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69   VFS "unix-dotfi
23460 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  le".**          
23470 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69  that uses dot-fi
23480 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  les in place of 
23490 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c  posix advisory l
234a0 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c  ocking..** <tr><
234b0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
234c0 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
234d0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
234e0 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
234f0 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
23500 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
23510 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
23520 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
23530 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
23540 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
23550 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
23560 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
23570 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
23580 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
23590 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
235a0 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
235b0 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
235c0 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
235d0 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
235e0 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
235f0 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
23600 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
23610 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
23620 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
23630 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
23640 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
23650 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
23660 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
23670 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
23680 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
23690 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
236a0 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
236b0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
236c0 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
236d0 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
236e0 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
236f0 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
23700 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
23710 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
23720 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
23730 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
23740 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
23750 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
23760 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
23770 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
23780 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
23790 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
237a0 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
237b0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
237c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
237d0 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
237e0 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
237f0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
23800 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
23810 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
23820 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
23830 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
23840 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
23850 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
23860 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
23870 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
23880 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
23890 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
238a0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
238b0 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
238c0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
238d0 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
238e0 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
238f0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
23900 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  g sqlite3_open()
23910 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
23920 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73  _v2().  Otherwis
23930 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
23940 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
23950 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
23960 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
23970 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ay fail..**.** S
23980 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
23990 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
239a0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
239b0 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
239c0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
239d0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
239e0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
239f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
23a00 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
23a10 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
23a20 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
23a30 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
23a40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
23a50 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
23a60 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
23a70 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
23a80 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
23a90 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
23aa0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
23ab0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
23ac0 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
23ad0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
23ae0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
23af0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
23b00 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
23b10 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
23b20 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
23b30 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
23b40 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
23b50 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
23b60 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
23b70 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
23b80 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
23b90 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
23ba0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
23bb0 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
23bc0 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
23bd0 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
23be0 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
23bf0 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
23c00 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
23c10 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
23c20 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
23c30 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
23c40 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
23c50 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
23c60 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
23c70 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
23c80 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
23c90 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
23ca0 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
23cb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
23cc0 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
23cd0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
23ce0 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
23cf0 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
23d00 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
23d10 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
23d20 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
23d30 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
23d40 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
23d50 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
23d60 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
23d70 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
23d80 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
23d90 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
23da0 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
23db0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
23dc0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
23dd0 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
23de0 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
23df0 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
23e00 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
23e10 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
23e20 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
23e30 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
23e40 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
23e50 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
23e60 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
23e70 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
23e80 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
23e90 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
23ea0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
23eb0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
23ec0 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
23ed0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
23ee0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
23ef0 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
23f00 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
23f10 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
23f20 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
23f30 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
23f40 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
23f50 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
23f60 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
23f70 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
23f80 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
23f90 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
23fa0 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
23fb0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
23fc0 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
23fd0 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
23fe0 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
23ff0 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
24000 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
24010 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
24020 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
24030 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
24040 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
24050 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
24060 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
24070 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
24080 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
24090 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
240a0 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
240b0 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
240c0 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
240d0 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
240e0 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
240f0 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
24100 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
24110 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
24120 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
24130 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
24140 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
24150 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
24160 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
24170 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
24180 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
24190 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
241a0 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
241b0 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
241c0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
241d0 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
241e0 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
241f0 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
24200 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
24210 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
24220 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
24230 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
24240 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
24250 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
24260 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
24270 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
24280 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
24290 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
242a0 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
242b0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
242c0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
242d0 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
242e0 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
242f0 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
24300 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
24310 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
24320 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
24330 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
24340 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
24350 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
24360 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
24370 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
24380 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
24390 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
243a0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
243b0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
243c0 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
243d0 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
243e0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
243f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69  .int sqlite3_uri
24400 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63  _boolean(const c
24410 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73  har *zFile, cons
24420 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20  t char *zParam, 
24430 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73  int bDefault);.s
24440 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
24450 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63  ite3_uri_int64(c
24460 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73  onst char*, cons
24470 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
24480 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _int64);.../*.**
24490 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
244a0 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
244b0 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ges.**.** ^The s
244c0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
244d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
244e0 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
244f0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
24500 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
24510 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
24520 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
24530 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
24540 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
24550 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
24560 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24570 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
24580 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
24590 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
245a0 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
245b0 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
245c0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
245d0 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
245e0 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
245f0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
24600 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
24610 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
24620 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
24630 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
24640 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
24650 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
24660 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
24670 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
24680 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
24690 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
246a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
246b0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
246c0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
246d0 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
246e0 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
246f0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
24700 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
24710 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
24720 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
24730 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
24740 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
24750 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
24760 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
24770 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
24780 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
24790 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
247a0 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
247b0 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
247c0 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
247d0 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
247e0 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
247f0 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
24800 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
24810 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
24820 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
24830 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ons.)^.**.** ^Th
24840 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72  e sqlite3_errstr
24850 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
24860 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68  urns the English
24870 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a  -language text.*
24880 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  * that describes
24890 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64   the [result cod
248a0 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a  e], as UTF-8..**
248b0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
248c0 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
248d0 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
248e0 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
248f0 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74  .** and must not
24900 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65   be freed by the
24910 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a   application)^..
24920 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
24930 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
24940 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
24950 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
24960 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
24970 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
24980 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
24990 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
249a0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
249b0 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
249c0 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
249d0 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
249e0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
249f0 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
24a00 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
24a10 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
24a20 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
24a30 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
24a40 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
24a50 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
24a60 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
24a70 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
24a80 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
24a90 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
24aa0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24ab0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
24ac0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
24ad0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
24ae0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
24af0 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
24b00 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
24b10 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
24b20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
24b30 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
24b40 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
24b50 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
24b60 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
24b70 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
24b80 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
24b90 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
24ba0 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
24bb0 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
24bc0 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
24bd0 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
24be0 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
24bf0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
24c00 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
24c10 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
24c20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
24c30 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
24c40 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73  be set..*/.int s
24c50 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
24c60 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74  qlite3 *db);.int
24c70 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
24c80 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
24c90 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68  3 *db);.const ch
24ca0 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
24cb0 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  sg(sqlite3*);.co
24cc0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
24cd0 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
24ce0 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  e3*);.const char
24cf0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72   *sqlite3_errstr
24d00 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
24d10 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74  PI3REF: SQL Stat
24d20 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
24d30 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61  KEYWORDS: {prepa
24d40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b  red statement} {
24d50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24d60 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  nts}.**.** An in
24d70 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
24d80 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
24d90 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
24da0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73  atement..** This
24db0 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f   object is vario
24dc0 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20  usly known as a 
24dd0 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  "prepared statem
24de0 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f  ent" or a.** "co
24df0 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65  mpiled SQL state
24e00 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20  ment" or simply 
24e10 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22  as a "statement"
24e20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65  ..**.** The life
24e30 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20   of a statement 
24e40 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65  object goes some
24e50 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a  thing like this:
24e60 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
24e70 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f  li> Create the o
24e80 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
24e90 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
24ea0 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a  )] or a related.
24eb0 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e  **      function
24ec0 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
24ed0 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70  alues to [host p
24ee0 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67  arameters] using
24ef0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
24f00 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e  d_*().**      in
24f10 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69  terfaces..** <li
24f20 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
24f30 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
24f40 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
24f50 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
24f60 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73  <li> Reset the s
24f70 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
24f80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
24f90 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
24fa0 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
24fb0 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
24fc0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
24fd0 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
24fe0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
24ff0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
25000 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ()]..** </ol>.**
25010 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63  .** Refer to doc
25020 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e  umentation on in
25030 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73  dividual methods
25040 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74   above for addit
25050 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
25060 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
25070 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
25080 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
25090 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
250a0 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d  EF: Run-time Lim
250b0 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  its.**.** ^(This
250c0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
250d0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61  s the size of va
250e0 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73  rious constructs
250f0 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a   to be limited.*
25100 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f  * on a connectio
25110 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  n by connection 
25120 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73  basis.  The firs
25130 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
25140 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
25150 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73  connection] whos
25160 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65  e limit is to be
25170 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e   set or queried.
25180 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
25190 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
251a0 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63   of the [limit c
251b0 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20  ategories] that 
251c0 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73  define a.** clas
251d0 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20  s of constructs 
251e0 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74  to be size limit
251f0 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70  ed.  The third p
25200 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
25210 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72  ** new limit for
25220 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e   that construct.
25230 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  )^.**.** ^If the
25240 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20   new limit is a 
25250 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c  negative number,
25260 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e   the limit is un
25270 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f  changed..** ^(Fo
25280 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74  r each limit cat
25290 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d  egory SQLITE_LIM
252a0 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74  IT_<i>NAME</i> t
252b0 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c  here is a .** [l
252c0 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70  imits | hard upp
252d0 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74  er bound].** set
252e0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
252f0 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65   by a C preproce
25300 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65  ssor macro calle
25310 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53  d.** [limits | S
25320 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d  QLITE_MAX_<i>NAM
25330 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20  E</i>]..** (The 
25340 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
25350 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
25360 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a   to "_MAX_".))^.
25370 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20  ** ^Attempts to 
25380 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
25390 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
253a0 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
253b0 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
253c0 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
253d0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a  d upper bound..*
253e0 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73  *.** ^Regardless
253f0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
25400 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73  ot the limit was
25410 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a   changed, the .*
25420 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  * [sqlite3_limit
25430 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
25440 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20  turns the prior 
25450 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d  value of the lim
25460 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74  it..** ^Hence, t
25470 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65  o find the curre
25480 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69  nt value of a li
25490 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e  mit without chan
254a0 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70  ging it,.** simp
254b0 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69  ly invoke this i
254c0 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68  nterface with th
254d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
254e0 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a  r set to -1..**.
254f0 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ** Run-time limi
25500 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
25510 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
25520 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
25530 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
25540 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
25550 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
25560 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
25570 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
25580 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
25590 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
255a0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
255b0 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
255c0 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73  e a.** web brows
255d0 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
255e0 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
255f0 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
25600 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
25610 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
25620 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
25630 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
25640 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
25650 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
25660 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
25670 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
25680 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
25690 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
256a0 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
256b0 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
256c0 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
256d0 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
256e0 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
256f0 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
25700 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
25710 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
25720 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  k.  Developers m
25730 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
25740 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
25750 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
25760 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
25770 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
25780 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
25790 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
257a0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
257b0 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
257c0 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
257d0 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
257e0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
257f0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
25800 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  PRAGMA]..**.** N
25810 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ew run-time limi
25820 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79  t categories may
25830 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
25840 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f  ure releases..*/
25850 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d  .int sqlite3_lim
25860 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
25870 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
25880 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25890 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
258a0 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
258b0 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
258c0 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
258d0 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
258e0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
258f0 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
25900 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
25910 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
25920 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
25930 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
25940 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
25950 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
25960 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
25970 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
25980 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
25990 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
259a0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
259b0 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
259c0 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
259d0 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
259e0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
259f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
25a00 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
25a10 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
25a20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25a30 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
25a40 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
25a50 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
25a60 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
25a70 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25a80 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
25a90 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25aa0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
25ab0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25ac0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
25ad0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
25ae0 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f  ent, in bytes.</
25af0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
25b00 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
25b10 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  N]] ^(<dt>SQLITE
25b20 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
25b30 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25b40 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
25b50 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
25b60 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
25b70 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
25b80 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
25b90 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
25ba0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
25bb0 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
25bc0 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
25bd0 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
25be0 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e  Y clause.</dd>)^
25bf0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25c00 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
25c10 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25c20 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
25c30 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25c40 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
25c50 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
25c60 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
25c70 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
25c80 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25c90 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d  COMPOUND_SELECT]
25ca0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
25cb0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
25cc0 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
25cd0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
25ce0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
25cf0 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
25d00 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
25d10 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
25d20 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
25d30 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25d40 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
25d50 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25d60 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
25d70 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
25d80 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
25d90 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
25da0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
25db0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
25dc0 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20    This limit is 
25dd0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  not currently.**
25de0 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67   enforced, thoug
25df0 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  h that might be 
25e00 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75  added in some fu
25e10 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
25e20 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29  ** SQLite.</dd>)
25e30 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
25e40 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
25e50 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ARG]] ^(<dt>SQLI
25e60 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
25e70 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
25e80 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
25e90 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
25ea0 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
25eb0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
25ec0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
25ed0 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51  ACHED]] ^(<dt>SQ
25ee0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
25ef0 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
25f00 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
25f10 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20  er of [ATTACH | 
25f20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
25f30 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  es].)^</dd>.**.*
25f40 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25f50 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
25f60 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  NGTH]].** ^(<dt>
25f70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
25f80 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
25f90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25fa0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
25fb0 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
25fc0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
25fd0 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
25fe0 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
25ff0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
26000 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
26010 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e  LE_NUMBER]].** ^
26020 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26030 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
26040 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
26050 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
26060 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
26070 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
26080 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
26090 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
260a0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
260b0 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
260c0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
260d0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
260e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
260f0 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
26100 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
26110 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
26120 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
26130 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c  ER_THREADS]] ^(<
26140 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26150 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f  WORKER_THREADS</
26160 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26170 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
26180 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65   auxiliary worke
26190 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20 61  r threads that a
261a0 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70   single.** [prep
261b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
261c0 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29  may start.</dd>)
261d0 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ^.** </dl>.*/.#d
261e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
261f0 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
26200 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
26210 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26220 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
26230 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
26240 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26250 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
26260 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
26270 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26280 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
26290 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
262a0 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
262b0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
262c0 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
262d0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
262e0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
262f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26300 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
26310 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
26320 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
26330 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
26340 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
26350 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
26360 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
26370 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
26380 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
26390 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
263a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
263b0 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
263c0 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
263d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
263e0 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20  GGER_DEPTH      
263f0 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
26400 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f   SQLITE_LIMIT_WO
26410 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20 20  RKER_THREADS    
26420 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a         11../*.**
26430 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
26440 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
26450 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  ement.** KEYWORD
26460 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e  S: {SQL statemen
26470 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a  t compiler}.**.*
26480 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20  * To execute an 
26490 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75  SQL query, it mu
264a0 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
264b0 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
264c0 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
264d0 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
264e0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
264f0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
26500 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73  gument, "db", is
26510 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
26520 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65  nection] obtaine
26530 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f  d from a.** prio
26540 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
26550 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
26560 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
26570 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  open_v2()] or.**
26580 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
26590 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61  ()].  The databa
265a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
265b0 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e  st not have been
265c0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
265d0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
265e0 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
265f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
26600 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
26610 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
26620 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
26630 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
26640 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
26650 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
26660 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
26670 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
26680 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26690 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
266a0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
266b0 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  * use UTF-16..**
266c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74  .** ^If the nByt
266d0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65  e argument is le
266e0 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68  ss than zero, th
266f0 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
26700 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
26710 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
26720 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
26730 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
26740 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61  hen it is the ma
26750 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20  ximum.** number 
26760 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66  of  bytes read f
26770 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e  rom zSql.  ^When
26780 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
26790 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a  gative, the.** z
267a0 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20  Sql string ends 
267b0 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69  at either the fi
267c0 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c  rst '\000' or '\
267d0 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72  u0000' character
267e0 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65   or.** the nByte
267f0 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65  -th byte, whiche
26800 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
26810 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
26820 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  nows.** that the
26830 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
26840 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
26850 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69  ed, then there i
26860 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72  s a small.** per
26870 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
26880 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20  ge to be gained 
26890 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  by passing an nB
268a0 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
268b0 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74  at.** is equal t
268c0 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  o the number of 
268d0 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
268e0 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
268f0 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68  luding</i>.** th
26900 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
26910 20 62 79 74 65 73 20 61 73 20 74 68 69 73 20 73   bytes as this s
26920 61 76 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d  aves SQLite from
26930 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61   having to.** ma
26940 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ke a copy of the
26950 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a   input string..*
26960 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20  *.** ^If pzTail 
26970 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
26980 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
26990 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
269a0 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70   first byte.** p
269b0 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
269c0 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  he first SQL sta
269d0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
269e0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
269f0 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20  only.** compile 
26a00 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d  the first statem
26a10 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20  ent in zSql, so 
26a20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20  *pzTail is left 
26a30 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77  pointing to.** w
26a40 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f  hat remains unco
26a50 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a  mpiled..**.** ^*
26a60 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
26a70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
26a80 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
26a90 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
26aa0 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
26ab0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
26ac0 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20  3_step()].  ^If 
26ad0 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f  there is an erro
26ae0 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  r, *ppStmt is se
26af0 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e  t.** to NULL.  ^
26b00 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78  If the input tex
26b10 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  t contains no SQ
26b20 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
26b30 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73  is an empty.** s
26b40 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65  tring or a comme
26b50 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74  nt) then *ppStmt
26b60 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e   is set to NULL.
26b70 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  .** The calling 
26b80 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
26b90 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
26ba0 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
26bb0 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
26bc0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
26bd0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
26be0 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
26bf0 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
26c00 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20   ppStmt may not 
26c10 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
26c20 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20  On success, the 
26c30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
26c40 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74  ) family of rout
26c50 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
26c60 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65  ITE_OK];.** othe
26c70 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
26c80 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
26c90 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
26ca0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
26cb0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
26cc0 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
26cd0 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
26ce0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
26cf0 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
26d00 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
26d10 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
26d20 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
26d30 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
26d40 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
26d50 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
26d60 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ged..** ^In the 
26d70 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "v2" interfaces,
26d80 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
26d90 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
26da0 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
26db0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
26dc0 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
26dd0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
26de0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
26df0 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
26e00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
26e10 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
26e20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66  to.** behave dif
26e30 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65  ferently in thre
26e40 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e ways:.**.** <o
26e50 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  l>.** <li>.** ^I
26e60 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
26e70 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
26e80 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
26e90 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
26ea0 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
26eb0 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
26ec0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
26ed0 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
26ee0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
26ef0 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
26f00 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
26f10 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d  n it again. As m
26f20 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d  any as [SQLITE_M
26f30 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d  AX_SCHEMA_RETRY]
26f40 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c  .** retries will
26f50 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71   occur before sq
26f60 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76  lite3_step() giv
26f70 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e  es up and return
26f80 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c  s an error..** <
26f90 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
26fa0 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f  ** ^When an erro
26fb0 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
26fc0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
26fd0 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
26fe0 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
26ff0 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
27000 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
27010 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67  odes].  ^The leg
27020 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
27030 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
27040 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
27050 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
27060 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
27070 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
27080 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c  .** and the appl
27090 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61  ication would ha
270a0 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
270b0 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
270c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
270d0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
270e0 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
270f0 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
27100 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
27110 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
27120 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
27130 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
27140 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
27150 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
27160 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
27170 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
27180 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63  ^If the specific
27190 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20   value bound to 
271a0 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73  [parameter | hos
271b0 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  t parameter] in 
271c0 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c  the .** WHERE cl
271d0 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75  ause might influ
271e0 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20  ence the choice 
271f0 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f  of query plan fo
27200 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a  r a statement,.*
27210 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65  * then the state
27220 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74  ment will be aut
27230 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
27240 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65  piled, as if the
27250 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20  re had been .** 
27260 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c  a schema change,
27270 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b   on the first  [
27280 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
27290 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  call following a
272a0 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20  ny change.** to 
272b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
272c0 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67  d_text | binding
272d0 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61  s] of that [para
272e0 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65  meter]. .** ^The
272f0 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
27300 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20  of WHERE-clause 
27310 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68  [parameter] migh
27320 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
27330 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75  .** choice of qu
27340 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20  ery plan if the 
27350 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
27360 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
27370 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f  of a [LIKE].** o
27380 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  r [GLOB] operato
27390 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61  r or if the para
273a0 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65  meter is compare
273b0 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20  d to an indexed 
273c0 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68  column.** and th
273d0 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  e [SQLITE_ENABLE
273e0 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d  _STAT3] compile-
273f0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
27400 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e  nabled..** </li>
27410 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ol>.*/.int
27420 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27430 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
27440 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
27450 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
27460 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
27470 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
27480 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
27490 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
274a0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
274b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
274c0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
274d0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
274e0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
274f0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
27500 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
27510 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
27520 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
27530 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
27540 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
27550 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
27560 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
27570 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
27580 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
27590 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
275a0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
275b0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
275c0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
275d0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
275e0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
275f0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
27600 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
27610 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
27620 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
27630 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
27640 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
27650 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
27660 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
27670 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
27680 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
27690 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
276a0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
276b0 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
276c0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
276d0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
276e0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
276f0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
27700 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
27710 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
27720 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
27730 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
27740 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
27750 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
27760 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
27770 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
27780 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
27790 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
277a0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
277b0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
277c0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
277d0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
277e0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
277f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
27800 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
27810 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
27820 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
27830 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
27840 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
27850 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
27860 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
27870 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
27880 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
27890 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
278a0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
278b0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
278c0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
278d0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
278e0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
278f0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
27900 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
27910 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
27920 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
27930 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
27940 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
27950 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
27960 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
27970 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
27980 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
27990 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
279a0 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
279b0 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
279c0 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
279d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
279e0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
279f0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
27a00 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
27a10 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
27a20 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
27a30 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
27a40 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
27a50 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
27a60 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
27a70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27a80 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
27a90 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57   SQL Statement W
27aa0 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61  rites The Databa
27ab0 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  se.**.** ^The sq
27ac0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
27ad0 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65  nly(X) interface
27ae0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
27af0 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61  on-zero) if.** a
27b00 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b  nd only if the [
27b10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27b20 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64  nt] X makes no d
27b30 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f  irect changes to
27b40 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
27b50 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
27b60 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  file..**.** Note
27b70 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69   that [applicati
27b80 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
27b90 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20  unctions] or.** 
27ba0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
27bb0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68   might change th
27bc0 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72  e database indir
27bd0 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20  ectly as a side 
27be0 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46  effect.  .** ^(F
27bf0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
27c00 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
27c10 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e  fines a function
27c20 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a   "eval()" that .
27c30 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65  ** calls [sqlite
27c40 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20  3_exec()], then 
27c50 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
27c60 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c  L statement woul
27c70 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  d.** change the 
27c80 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
27c90 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63  rough side-effec
27ca0 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ts:.**.** <block
27cb0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
27cc0 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44    SELECT eval('D
27cd0 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20  ELETE FROM t1') 
27ce0 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72  FROM t2;.** </pr
27cf0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
27d00 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73  **.** But becaus
27d10 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  e the [SELECT] s
27d20 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
27d30 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
27d40 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69  abase file.** di
27d50 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f  rectly, sqlite3_
27d60 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
27d70 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75  would still retu
27d80 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a  rn true.)^.**.**
27d90 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f   ^Transaction co
27da0 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73  ntrol statements
27db0 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d   such as [BEGIN]
27dc0 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c  , [COMMIT], [ROL
27dd0 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45  LBACK],.** [SAVE
27de0 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c  POINT], and [REL
27df0 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69  EASE] cause sqli
27e00 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
27e10 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
27e20 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ue,.** since the
27e30 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d   statements them
27e40 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63  selves do not ac
27e50 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68  tually modify th
27e60 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a  e database but.*
27e70 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f  * rather they co
27e80 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67  ntrol the timing
27e90 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73   of when other s
27ea0 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79  tatements modify
27eb0 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73   the .** databas
27ec0 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48  e.  ^The [ATTACH
27ed0 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73  ] and [DETACH] s
27ee0 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63  tatements also c
27ef0 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ause.** sqlite3_
27f00 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
27f10 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  to return true s
27f20 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73  ince, while thos
27f30 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  e statements.** 
27f40 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69  change the confi
27f50 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61  guration of a da
27f60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27f70 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d  n, they do not m
27f80 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20  ake .** changes 
27f90 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  to the content o
27fa0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
27fb0 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f  iles on disk..*/
27fc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
27fd0 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
27fe0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
27ff0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28000 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
28010 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
28020 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
28030 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  et.**.** ^The sq
28040 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
28050 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  S) interface ret
28060 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
28070 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b  ero) if the.** [
28080 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28090 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73  nt] S has been s
280a0 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20  tepped at least 
280b0 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  once using .** [
280c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
280d0 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e   but has not run
280e0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
280f0 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a  nd/or has not .*
28100 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69  * been reset usi
28110 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
28120 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c  t(S)].  ^The sql
28130 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
28140 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
28150 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20  eturns false if 
28160 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
28170 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f  ter.  If S is no
28180 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  t a .** NULL poi
28190 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20  nter and is not 
281a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
281b0 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73  alid [prepared s
281c0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
281d0 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ect, then the be
281e0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
281f0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
28200 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a   undesirable..**
28210 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
28220 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ce can be used i
28230 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73  n combination [s
28240 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
28250 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65  ()].** to locate
28260 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74   all prepared st
28270 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
28280 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62  ted with a datab
28290 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  ase .** connecti
282a0 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e  on that are in n
282b0 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73  eed of being res
282c0 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65  et.  This can be
282d0 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78   used,.** for ex
282e0 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f  ample, in diagno
282f0 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f  stic routines to
28300 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70   search for prep
28310 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65  ared .** stateme
28320 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c  nts that are hol
28330 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ding a transacti
28340 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20  on open..*/.int 
28350 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
28360 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  y(sqlite3_stmt*)
28370 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28380 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
28390 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
283a0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
283b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
283c0 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
283d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
283e0 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
283f0 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
28400 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
28410 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
28420 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
28430 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
28440 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
28450 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
28460 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
28470 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
28480 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
28490 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
284a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
284b0 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
284c0 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
284d0 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
284e0 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
284f0 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
28500 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
28510 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
28520 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
28530 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
28540 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
28550 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
28560 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28570 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
28580 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
28590 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
285a0 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
285b0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
285c0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
285d0 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
285e0 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
285f0 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
28600 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
28610 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
28620 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
28630 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28640 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
28650 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
28660 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
28670 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
28680 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
28690 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
286a0 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d  .  An internal m
286b0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
286c0 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
286d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
286e0 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
286f0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
28700 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
28710 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28720 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
28730 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
28740 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
28750 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
28760 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
28770 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
28780 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
28790 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
287a0 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
287b0 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
287c0 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
287d0 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
287e0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
287f0 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
28800 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
28810 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
28820 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
28830 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
28840 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
28850 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
28860 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
28870 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
28880 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
28890 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
288a0 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
288b0 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
288c0 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
288d0 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
288e0 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
288f0 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
28900 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
28910 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
28920 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
28930 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
28940 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74   when not strict
28950 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ly required..**.
28960 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28970 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
28980 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
28990 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
289a0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
289b0 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
289c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
289d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
289e0 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
289f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
28a00 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
28a10 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
28a20 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
28a30 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
28a40 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
28a50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
28a60 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
28a70 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
28a80 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
28a90 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
28aa0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
28ab0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
28ac0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
28ad0 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
28ae0 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
28af0 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
28b00 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
28b10 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
28b20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
28b30 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
28b40 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
28b50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
28b60 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
28b70 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
28b80 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
28b90 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
28ba0 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
28bb0 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
28bc0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
28bd0 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f  t object.  ^A po
28be0 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
28bf0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
28c00 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ct.** is always 
28c10 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
28c20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  to [application-
28c30 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
28c40 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
28c50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
28c60 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
28c70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
28c80 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a  ill pass this.**
28c90 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68   pointer through
28ca0 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b   into calls to [
28cb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
28cc0 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73  nt | sqlite3_res
28cd0 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ult()],.** [sqli
28ce0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
28cf0 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74  ntext()], [sqlit
28d00 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c  e3_user_data()],
28d10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
28d20 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
28d30 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ], [sqlite3_get_
28d40 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61  auxdata()],.** a
28d50 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  nd/or [sqlite3_s
28d60 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a  et_auxdata()]..*
28d70 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
28d80 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
28d90 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
28da0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28db0 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  F: Binding Value
28dc0 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
28dd0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57  atements.** KEYW
28de0 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61  ORDS: {host para
28df0 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72  meter} {host par
28e00 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70  ameters} {host p
28e10 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a  arameter name}.*
28e20 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
28e30 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c   parameter} {SQL
28e40 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61   parameters} {pa
28e50 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d  rameter binding}
28e60 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20  .**.** ^(In the 
28e70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
28e80 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  xt input to [sql
28e90 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
28ea0 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
28eb0 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
28ec0 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
28ed0 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72   by a [parameter
28ee0 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f  ] that matches o
28ef0 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a  ne of following.
28f00 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a  ** templates:.**
28f10 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
28f20 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
28f30 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
28f40 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
28f50 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
28f60 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
28f70 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76  e templates abov
28f80 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74  e, NNN represent
28f90 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
28fa0 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
28fb0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61   represents an a
28fc0 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e  lphanumeric iden
28fd0 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20  tifier.)^  ^The 
28fe0 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
28ff0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
29000 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
29010 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
29020 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
29030 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
29040 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
29050 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
29060 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
29070 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   here..**.** ^Th
29080 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
29090 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
290a0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
290b0 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
290c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
290d0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
290e0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
290f0 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
29100 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
29110 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
29120 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
29130 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
29140 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
29150 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
29160 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  e set..** ^The l
29170 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
29180 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
29190 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20  ex of 1.  ^When 
291a0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
291b0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
291c0 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
291d0 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
291e0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
291f0 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
29200 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
29210 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
29220 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68  currence..** ^Th
29230 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
29240 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
29250 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
29260 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
29270 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29280 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
29290 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68  if desired.  ^Th
292a0 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
292b0 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
292c0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
292d0 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e   NNN..** ^The NN
292e0 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
292f0 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
29300 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
29310 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
29320 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
29330 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
29340 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
29350 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  999)..**.** ^The
29360 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
29370 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
29380 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
29390 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  meter..** ^If th
293a0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
293b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
293c0 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
293d0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
293e0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
293f0 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61  bind_blob() is a
29400 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
29410 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  en the fourth pa
29420 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67  rameter.** is ig
29430 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e  nored and the en
29440 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20  d result is the 
29450 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f  same as sqlite3_
29460 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a  bind_null()..**.
29470 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
29480 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
29490 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
294a0 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
294b0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
294c0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
294d0 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
294e0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
294f0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
29500 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
29510 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
29520 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
29530 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
29540 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
29550 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
29560 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
29570 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
29580 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
29590 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
295a0 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  n the length of 
295b0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
295c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
295d0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
295e0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
295f0 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ator..** If the 
29600 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
29610 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
29620 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74  _blob() is negat
29630 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ive, then.** the
29640 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
29650 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20  efined..** If a 
29660 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75  non-negative fou
29670 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
29680 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c   provided to sql
29690 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
296a0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
296b0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20  ind_text16() or 
296c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
296d0 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68  t64() then.** th
296e0 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  at parameter mus
296f0 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
29700 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68  fset.** where th
29710 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
29720 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73   would occur ass
29730 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67  uming the string
29740 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72   were NUL.** ter
29750 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
29760 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
29770 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66  occur at byte of
29780 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20  fsets less than 
29790 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66  .** the value of
297a0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
297b0 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72  meter then the r
297c0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
297d0 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f  value will.** co
297e0 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
297f0 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ULs.  The result
29800 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
29810 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67  involving string
29820 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64  s.** with embedd
29830 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
29840 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
29850 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
29860 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20  to the BLOB and 
29870 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69  string binding i
29880 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
29890 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
298a0 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
298b0 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
298c0 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
298d0 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
298e0 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
298f0 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
29900 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
29910 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
29920 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
29930 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64  the call to bind
29940 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e   API fails..** ^
29950 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
29960 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
29970 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
29980 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
29990 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
299a0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
299b0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
299c0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
299d0 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
299e0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
299f0 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74   freed..** ^If t
29a00 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
29a10 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
29a20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
29a30 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
29a40 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
29a50 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
29a60 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
29a70 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
29a80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
29a90 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
29aa0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
29ab0 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
29ac0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
29ad0 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62  _text64() must b
29ae0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c  e one of.** [SQL
29af0 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
29b00 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49  TE_UTF16], [SQLI
29b10 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20  TE_UTF16BE], or 
29b20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
29b30 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74  .** to specify t
29b40 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74  he encoding of t
29b50 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74  he text in the t
29b60 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20  hird parameter. 
29b70 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68   If.** the sixth
29b80 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
29b90 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
29ba0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
29bb0 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20   the.** allowed 
29bc0 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f  values shown abo
29bd0 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65  ve, or if the te
29be0 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  xt encoding is d
29bf0 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d  ifferent.** from
29c00 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
29c10 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ecified by the s
29c20 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  ixth parameter, 
29c30 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
29c40 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  r.** is undefine
29c50 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
29c60 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
29c70 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
29c80 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
29c90 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
29ca0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
29cb0 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
29cc0 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
29cd0 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
29ce0 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
29cf0 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
29d00 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
29d10 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
29d20 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
29d30 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
29d40 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
29d50 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
29d60 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
29d70 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
29d80 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
29d90 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
29da0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
29db0 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
29dc0 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
29dd0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
29de0 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
29df0 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
29e00 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
29e10 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
29e20 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
29e30 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
29e40 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
29e50 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
29e60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29e70 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
29e80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29e90 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
29ea0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
29eb0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
29ec0 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
29ed0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
29ee0 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
29ef0 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
29f00 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
29f10 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
29f20 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
29f30 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
29f40 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
29f50 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
29f60 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
29f70 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
29f80 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
29f90 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
29fa0 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
29fb0 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
29fc0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
29fd0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
29fe0 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
29ff0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
2a000 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
2a010 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
2a020 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
2a030 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
2a040 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
2a050 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
2a060 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
2a070 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
2a080 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f  ..** ^[SQLITE_TO
2a090 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72  OBIG] might be r
2a0a0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73  eturned if the s
2a0b0 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20  ize of a string 
2a0c0 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65  or BLOB.** excee
2a0d0 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65  ds limits impose
2a0e0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  d by [sqlite3_li
2a0f0 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
2a100 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a  IT_LENGTH]) or.*
2a110 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45  * [SQLITE_MAX_LE
2a120 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  NGTH]..** ^[SQLI
2a130 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
2a140 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
2a150 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
2a160 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
2a170 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
2a180 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
2a190 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
2a1a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2a1b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2a1c0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2a1d0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2a1e0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2a1f0 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
2a200 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a210 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2a220 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a230 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2a240 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2a250 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
2a260 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2a270 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2a280 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73  blob64(sqlite3_s
2a290 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2a2a0 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f   void*, sqlite3_
2a2b0 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
2a2c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a2d0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2a2e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2a2f0 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
2a300 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
2a310 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
2a320 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
2a330 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
2a340 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
2a350 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
2a360 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2a370 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2a380 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a390 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
2a3a0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
2a3b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2a3c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2a3d0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69  nt,const char*,i
2a3e0 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
2a3f0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2a400 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
2a410 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2a420 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2a430 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2a440 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2a450 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74  ind_text64(sqlit
2a460 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2a470 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
2a480 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20  te3_uint64,.    
2a490 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a4a0 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
2a4b0 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68  d*), unsigned ch
2a4c0 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e  ar encoding);.in
2a4d0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
2a4e0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
2a4f0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
2a500 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2a510 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a520 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
2a530 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2a540 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
2a550 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
2a560 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a   SQL Parameters.
2a570 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
2a580 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
2a590 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
2a5a0 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d  er of [SQL param
2a5b0 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b  eters].** in a [
2a5c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a5d0 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  nt].  SQL parame
2a5e0 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
2a5f0 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
2a600 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
2a610 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
2a620 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
2a630 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
2a640 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
2a650 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
2a660 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
2a670 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
2a680 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
2a690 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
2a6a0 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  ^(This routine a
2a6b0 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
2a6c0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2a6d0 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
2a6e0 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
2a6f0 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
2a700 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
2a710 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
2a720 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
2a730 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
2a740 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
2a750 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2a760 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73  ?NNN form are us
2a770 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79  ed,.** there may
2a780 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20   be gaps in the 
2a790 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  list.)^.**.** Se
2a7a0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2a7b0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2a7c0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2a7d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a7e0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
2a7f0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2a800 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2a810 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
2a820 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a830 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
2a840 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2a850 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
2a860 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
2a870 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68  ameter.**.** ^Th
2a880 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
2a890 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c  arameter_name(P,
2a8a0 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
2a8b0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  urns.** the name
2a8c0 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51   of the N-th [SQ
2a8d0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
2a8e0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2a8f0 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
2a900 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20  (SQL parameters 
2a910 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
2a920 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
2a930 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
2a940 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
2a950 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
2a960 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
2a970 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
2a980 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
2a990 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
2a9a0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
2a9b0 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
2a9c0 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
2a9d0 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
2a9e0 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
2a9f0 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61  name.)^.** ^Para
2aa00 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
2aa10 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
2aa20 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
2aa30 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
2aa40 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72  ** and are refer
2aa50 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c  red to as "namel
2aa60 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f  ess" or "anonymo
2aa70 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a  us parameters"..
2aa80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2aa90 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
2aaa0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
2aab0 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
2aac0 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20  ^If the value N 
2aad0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
2aae0 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70  or if the N-th p
2aaf0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
2ab00 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
2ab10 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
2ab20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2ab30 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
2ab40 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
2ab50 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
2ab60 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
2ab70 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
2ab80 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
2ab90 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
2aba0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
2abb0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
2abc0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
2abd0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2abe0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2abf0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2ac00 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2ac10 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2ac20 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
2ac30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2ac40 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2ac50 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2ac60 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
2ac70 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
2ac80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
2ac90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2aca0 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
2acb0 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
2acc0 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20  iven Name.**.** 
2acd0 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
2ace0 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
2acf0 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
2ad00 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
2ad10 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
2ad20 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
2ad30 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
2ad40 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
2ad50 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
2ad60 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2ad70 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
2ad80 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
2ad90 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
2ada0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
2adb0 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
2adc0 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
2add0 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
2ade0 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
2adf0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
2ae00 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
2ae10 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
2ae20 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
2ae30 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2ae40 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
2ae50 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2ae60 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2ae70 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
2ae80 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2ae90 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
2aea0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2aeb0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2aec0 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
2aed0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2aee0 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
2aef0 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
2af00 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
2af10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2af20 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
2af30 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
2af40 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
2af50 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
2af60 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
2af70 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
2af80 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
2af90 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
2afa0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2afb0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
2afc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2afd0 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69  nt]..** ^Use thi
2afe0 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
2aff0 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
2b000 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
2b010 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2b020 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
2b030 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2b040 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2b050 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
2b060 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2b070 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2b080 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2b090 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2b0a0 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
2b0b0 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
2b0c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2b0d0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
2b0e0 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
2b0f0 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
2b100 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
2b110 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
2b120 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
2b130 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
2b140 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2b150 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2b160 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
2b170 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2b180 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2b190 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2b1a0 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
2b1b0 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
2b1c0 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  Set.**.** ^These
2b1d0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2b1e0 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
2b1f0 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
2b200 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
2b210 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
2b220 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
2b230 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
2b240 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2b250 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
2b260 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2b270 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2b280 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
2b290 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
2b2a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2b2b0 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
2b2c0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2b2d0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
2b2e0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2b2f0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2b300 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
2b310 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2b320 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
2b330 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
2b340 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
2b350 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2b360 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
2b370 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
2b380 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
2b390 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
2b3a0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2b3b0 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
2b3c0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
2b3d0 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
2b3e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2b3f0 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
2b400 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2b410 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2b420 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2b430 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2b440 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2b450 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2b460 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2b470 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2b480 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2b490 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
2b4a0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2b4b0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
2b4c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2b4d0 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
2b4e0 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
2b4f0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
2b500 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
2b510 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
2b520 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
2b530 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
2b540 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
2b550 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
2b560 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
2b570 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
2b580 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2b590 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
2b5a0 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
2b5b0 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
2b5c0 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
2b5d0 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
2b5e0 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
2b5f0 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
2b600 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
2b610 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
2b620 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
2b630 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
2b640 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
2b650 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
2b660 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
2b670 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
2b680 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  next..*/.const c
2b690 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2b6a0 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
2b6b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
2b6c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2b6d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2b6e0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2b6f0 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
2b700 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
2b710 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
2b720 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
2b730 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2b740 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
2b750 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
2b760 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
2b770 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
2b780 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
2b790 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
2b7a0 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
2b7b0 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
2b7c0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2b7d0 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
2b7e0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
2b7f0 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
2b800 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
2b810 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
2b820 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
2b830 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
2b840 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
2b850 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
2b860 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
2b870 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
2b880 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2b890 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
2b8a0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
2b8b0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2b8c0 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
2b8d0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2b8e0 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
2b8f0 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
2b900 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b910 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
2b920 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2b930 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2b940 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2b950 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2b960 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2b970 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2b980 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2b990 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2b9a0 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2b9b0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
2b9c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2b9d0 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
2b9e0 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
2b9f0 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
2ba00 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
2ba10 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
2ba20 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
2ba30 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
2ba40 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
2ba50 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
2ba60 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2ba70 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
2ba80 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
2ba90 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2baa0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
2bab0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2bac0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2bad0 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
2bae0 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
2baf0 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
2bb00 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
2bb10 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
2bb20 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
2bb30 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
2bb40 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
2bb50 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
2bb60 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
2bb70 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
2bb80 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
2bb90 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2bba0 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
2bbb0 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
2bbc0 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
2bbd0 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
2bbe0 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
2bbf0 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
2bc00 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
2bc10 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
2bc20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
2bc30 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2bc40 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
2bc50 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
2bc60 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
2bc70 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
2bc80 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
2bc90 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
2bca0 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
2bcb0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
2bcc0 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
2bcd0 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
2bce0 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
2bcf0 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
2bd00 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
2bd10 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
2bd20 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2bd30 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
2bd40 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
2bd50 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
2bd60 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
2bd70 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
2bd80 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
2bd90 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
2bda0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
2bdb0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
2bdc0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
2bdd0 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
2bde0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2bdf0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2be00 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
2be10 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2be20 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
2be30 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
2be40 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
2be50 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
2be60 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2be70 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
2be80 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
2be90 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
2bea0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
2beb0 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
2bec0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2bed0 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
2bee0 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
2bef0 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
2bf00 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
2bf10 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
2bf20 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
2bf30 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2bf40 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2bf50 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2bf60 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2bf70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2bf80 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
2bf90 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2bfa0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2bfb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2bfc0 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
2bfd0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2bfe0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2bff0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
2c000 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2c010 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
2c020 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2c030 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
2c040 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2c050 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
2c060 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2c070 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
2c080 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2c090 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2c0a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2c0b0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2c0c0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2c0d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2c0e0 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
2c0f0 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
2c100 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
2c110 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2c120 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2c130 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
2c140 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
2c150 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
2c160 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
2c170 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
2c180 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
2c190 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
2c1a0 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
2c1b0 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
2c1c0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
2c1d0 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
2c1e0 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
2c1f0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
2c200 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
2c210 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
2c220 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2c230 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2c240 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
2c250 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
2c260 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
2c270 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
2c280 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
2c290 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
2c2a0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
2c2b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
2c2c0 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
2c2d0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2c2e0 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
2c2f0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
2c300 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
2c310 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
2c320 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
2c330 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
2c340 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
2c350 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
2c360 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
2c370 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
2c380 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
2c390 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
2c3a0 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
2c3b0 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
2c3c0 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
2c3d0 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
2c3e0 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
2c3f0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
2c400 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
2c410 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
2c420 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
2c430 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
2c440 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
2c450 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
2c460 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
2c470 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
2c480 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
2c490 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
2c4a0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
2c4b0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
2c4c0 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
2c4d0 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
2c4e0 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
2c4f0 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
2c500 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2c510 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
2c520 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
2c530 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
2c540 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
2c550 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e  e values..*/.con
2c560 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2c570 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
2c580 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2c590 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2c5a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2c5b0 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
2c5c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
2c5d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c5e0 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
2c5f0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
2c600 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
2c610 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
2c620 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
2c630 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b  sing either.** [
2c640 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c650 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
2c660 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2c670 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
2c680 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2c690 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
2c6a0 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
2c6b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2c6c0 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
2c6d0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
2c6e0 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
2c6f0 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
2c700 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
2c710 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
2c720 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
2c730 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
2c740 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
2c750 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
2c760 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
2c770 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
2c780 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
2c790 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
2c7a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2c7b0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
2c7c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c7d0 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
2c7e0 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
2c7f0 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
2c800 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
2c810 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c820 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
2c830 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
2c840 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
2c850 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
2c860 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
2c870 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
2c880 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
2c890 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
2c8a0 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
2c8b0 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
2c8c0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
2c8d0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
2c8e0 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
2c8f0 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
2c900 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
2c910 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
2c920 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
2c930 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
2c940 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32  ** ^With the "v2
2c950 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
2c960 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
2c970 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
2c980 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
2c990 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
2c9a0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
2c9b0 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
2c9c0 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
2c9d0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
2c9e0 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
2c9f0 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
2ca00 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
2ca10 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
2ca20 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
2ca30 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2ca40 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
2ca50 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
2ca60 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
2ca70 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
2ca80 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
2ca90 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
2caa0 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
2cab0 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
2cac0 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
2cad0 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a  urs within an.**
2cae0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2caf0 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73  ction then you s
2cb00 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74  hould rollback t
2cb10 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
2cb20 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75  efore.** continu
2cb30 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ing..**.** ^[SQL
2cb40 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
2cb50 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
2cb60 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
2cb70 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
2cb80 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
2cb90 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2cba0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2cbb0 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
2cbc0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
2cbd0 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
2cbe0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2cbf0 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
2cc00 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
2cc10 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
2cc20 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
2cc30 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te..**.** ^If th
2cc40 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2cc50 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
2cc60 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
2cc70 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   then [SQLITE_RO
2cc80 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  W].** is returne
2cc90 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
2cca0 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
2ccb0 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65   ready for proce
2ccc0 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20  ssing by the.** 
2ccd0 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
2cce0 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
2ccf0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f  ed using the [co
2cd00 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2cd10 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
2cd20 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
2cd30 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
2cd40 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
2cd50 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ow of data..**.*
2cd60 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  * ^[SQLITE_ERROR
2cd70 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
2cd80 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
2cd90 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
2cda0 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
2cdb0 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
2cdc0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2cdd0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
2cde0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
2cdf0 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
2ce00 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
2ce10 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
2ce20 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
2ce30 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  g()]..** ^With t
2ce40 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2ce50 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
2ce60 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2ce70 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
2ce80 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
2ce90 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
2cea0 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
2ceb0 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
2cec0 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
2ced0 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
2cee0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2cef0 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
2cf00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cf10 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22  ent].  ^In the "
2cf20 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
2cf30 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
2cf40 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
2cf50 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
2cf60 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
2cf70 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
2cf80 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
2cf90 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
2cfa0 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
2cfb0 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
2cfc0 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
2cfd0 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
2cfe0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2cff0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
2d000 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
2d010 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2d020 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
2d030 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
2d040 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
2d050 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2d060 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
2d070 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
2d080 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
2d090 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
2d0a0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
2d0b0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
2d0c0 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
2d0d0 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
2d0e0 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
2d0f0 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
2d100 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69  ** For all versi
2d110 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70  ons of SQLite up
2d120 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e   to and includin
2d130 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61  g 3.6.23.1, a ca
2d140 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2d150 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72  3_reset()] was r
2d160 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71  equired after sq
2d170 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74  lite3_step() ret
2d180 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a  urned anything.*
2d190 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  * other than [SQ
2d1a0 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65  LITE_ROW] before
2d1b0 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
2d1c0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
2d1d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2d1e0 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73    Failure to res
2d1f0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
2d200 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
2d210 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2d220 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75  et()] would resu
2d230 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  lt in an [SQLITE
2d240 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20  _MISUSE] return 
2d250 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
2d260 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74  step().  But aft
2d270 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32  er version 3.6.2
2d280 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  3.1, sqlite3_ste
2d290 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c  p() began.** cal
2d2a0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2d2b0 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63  set()] automatic
2d2c0 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
2d2d0 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
2d2e0 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69  .** than returni
2d2f0 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
2d300 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74  E].  This is not
2d310 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f   considered a co
2d320 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62  mpatibility.** b
2d330 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79  reak because any
2d340 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
2d350 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20  t ever receives 
2d360 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  an SQLITE_MISUSE
2d370 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f   error.** is bro
2d380 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f  ken by definitio
2d390 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  n.  The [SQLITE_
2d3a0 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20  OMIT_AUTORESET] 
2d3b0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2d3c0 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ion.** can be us
2d3d0 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68  ed to restore th
2d3e0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
2d3f0 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  r..**.** <b>Goof
2d400 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
2d410 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
2d420 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2d430 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2d440 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
2d450 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
2d460 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
2d470 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
2d480 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
2d490 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
2d4a0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
2d4b0 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
2d4c0 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
2d4d0 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
2d4e0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
2d4f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2d500 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
2d510 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
2d520 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
2d530 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
2d540 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
2d550 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
2d560 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
2d570 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
2d580 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
2d590 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
2d5a0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2d5b0 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
2d5c0 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
2d5d0 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
2d5e0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68  ts.** using eith
2d5f0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
2d600 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2d610 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2d620 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v2()] instead.**
2d630 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
2d640 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2d650 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2d660 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
2d670 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
2d680 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
2d690 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2d6a0 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
2d6b0 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
2d6c0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
2d6d0 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32  e use of the "v2
2d6e0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2d6f0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69  ecommended..*/.i
2d700 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  nt sqlite3_step(
2d710 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2d720 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d730 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
2d740 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
2d750 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  et.**.** ^The sq
2d760 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2d770 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2d780 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2d790 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2d7a0 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f  he.** current ro
2d7b0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2d7c0 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
2d7d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
2d7e0 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73  * ^If prepared s
2d7f0 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20  tatement P does 
2d800 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73  not have results
2d810 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
2d820 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74  .** (via calls t
2d830 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
2d840 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69  olumn_int | sqli
2d850 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20  te3_column_*()] 
2d860 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
2d870 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64  ) then sqlite3_d
2d880 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74  ata_count(P) ret
2d890 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  urns 0..** ^The 
2d8a0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2d8b0 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c  nt(P) routine al
2d8c0 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  so returns 0 if 
2d8d0 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  P is a NULL poin
2d8e0 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ter..** ^The sql
2d8f0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2d900 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  P) routine retur
2d910 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76  ns 0 if the prev
2d920 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ious call to.** 
2d930 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
2d940 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  ) returned [SQLI
2d950 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20  TE_DONE].  ^The 
2d960 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2d970 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  nt(P).** will re
2d980 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66  turn non-zero if
2d990 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2d9a0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  o [sqlite3_step]
2d9b0 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  (P) returned.** 
2d9c0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78  [SQLITE_ROW], ex
2d9d0 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65  cept in the case
2d9e0 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20   of the [PRAGMA 
2d9f0 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75  incremental_vacu
2da00 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20  um].** where it 
2da10 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a  always returns z
2da20 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73  ero since each s
2da30 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74  tep of that mult
2da40 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61  i-step.** pragma
2da50 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d   returns 0 colum
2da60 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ns of data..**.*
2da70 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2da80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2da90 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
2daa0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
2dab0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2dac0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2dad0 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
2dae0 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
2daf0 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
2db00 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
2db10 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
2db20 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
2db30 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
2db40 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
2db50 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
2db60 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
2db70 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
2db80 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
2db90 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
2dba0 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
2dbb0 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
2dbc0 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
2dbd0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2dbe0 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
2dbf0 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
2dc00 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
2dc10 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
2dc20 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
2dc30 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
2dc40 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
2dc50 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
2dc60 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
2dc70 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
2dc80 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
2dc90 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
2dca0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2dcb0 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
2dcc0 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
2dcd0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
2dce0 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
2dcf0 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
2dd00 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
2dd10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2dd20 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
2dd30 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
2dd40 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
2dd50 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
2dd60 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
2dd70 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
2dd80 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
2dd90 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
2dda0 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
2ddb0 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
2ddc0 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
2ddd0 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
2dde0 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
2ddf0 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
2de00 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
2de10 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
2de20 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2de30 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c   form the "resul
2de40 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65  t set" interface
2de50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
2de60 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
2de70 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
2de80 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
2de90 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
2dea0 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
2deb0 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65   a query.  ^In e
2dec0 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
2ded0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
2dee0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
2def0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2df00 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
2df10 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
2df20 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
2df30 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
2df40 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
2df50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2df60 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2df70 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
2df80 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
2df90 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2dfa0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
2dfb0 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
2dfc0 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
2dfd0 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
2dfe0 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  . ^The leftmost 
2dff0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
2e000 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
2e010 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68   index 0..** ^Th
2e020 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2e030 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
2e040 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
2e050 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
2e060 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2e070 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  nt()]..**.** If 
2e080 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2e090 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
2e0a0 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
2e0b0 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
2e0c0 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
2e0d0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2e0e0 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
2e0f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2e100 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2e110 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
2e120 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
2e130 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2e140 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2e150 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
2e160 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
2e170 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
2e180 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2e190 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
2e1a0 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
2e1b0 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
2e1c0 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
2e1d0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2e1e0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
2e1f0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
2e200 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
2e210 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2e220 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
2e230 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2e240 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
2e250 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
2e260 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
2e270 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2e280 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
2e290 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2e2a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
2e2b0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
2e2c0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
2e2d0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
2e2e0 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
2e2f0 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
2e300 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
2e310 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
2e320 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2e330 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2e340 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e350 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2e360 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2e370 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
2e380 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
2e390 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
2e3a0 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
2e3b0 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
2e3c0 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
2e3d0 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
2e3e0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
2e3f0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
2e400 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
2e410 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
2e420 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
2e430 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
2e440 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
2e450 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2e460 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2e470 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
2e480 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
2e490 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
2e4a0 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
2e4b0 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
2e4c0 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
2e4d0 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
2e4e0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
2e4f0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2e500 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
2e510 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
2e520 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
2e530 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
2e540 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
2e550 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2e560 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
2e570 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
2e580 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ion..**.** ^If t
2e590 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
2e5a0 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
2e5b0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
2e5c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e5d0 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
2e5e0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2e5f0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2e600 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
2e610 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2e620 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
2e630 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
2e640 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e650 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
2e660 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
2e670 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
2e680 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2e690 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2e6a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2e6b0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2e6c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2e6d0 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
2e6e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
2e6f0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
2e700 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
2e710 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
2e720 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
2e730 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2e740 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
2e750 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2e760 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
2e770 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2e780 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
2e790 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
2e7a0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2e7b0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
2e7c0 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
2e7d0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2e7e0 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
2e7f0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2e800 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2e810 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2e820 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2e830 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2e840 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
2e850 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2e860 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
2e870 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
2e880 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
2e890 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
2e8a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2e8b0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
2e8c0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
2e8d0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
2e8e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e8f0 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
2e900 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2e910 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
2e920 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
2e930 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
2e940 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2e950 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2e960 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
2e970 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2e980 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2e990 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e9a0 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
2e9b0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
2e9c0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
2e9d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
2e9e0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
2e9f0 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
2ea00 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
2ea10 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
2ea20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
2ea30 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
2ea40 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
2ea50 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
2ea60 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
2ea70 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2ea80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ea90 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2eaa0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2eab0 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
2eac0 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
2ead0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
2eae0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2eaf0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
2eb00 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
2eb10 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2eb20 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
2eb30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2eb40 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
2eb50 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
2eb60 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d  are always zero-
2eb70 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
2eb80 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
2eb90 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
2eba0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
2ebb0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
2ebc0 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
2ebd0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
2ebe0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
2ebf0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
2ec00 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2ec10 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
2ec20 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2ec30 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75  e] object.  An u
2ec40 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2ec50 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a  e3_value object.
2ec60 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ** may only be u
2ec70 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  sed with [sqlite
2ec80 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
2ec90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
2eca0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
2ecb0 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
2ecc0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2ecd0 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
2ece0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
2ecf0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2ed00 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
2ed10 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
2ed20 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
2ed30 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
2ed40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2ed50 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
2ed60 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
2ed70 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
2ed80 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
2ed90 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2eda0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2edb0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2edc0 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63  nes attempt to c
2edd0 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
2ede0 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61   where appropria
2edf0 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61  te.  ^For.** exa
2ee00 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
2ee10 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
2ee20 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
2ee30 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
2ee40 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
2ee50 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2ee60 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
2ee70 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66  ternally to perf
2ee80 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65  orm the.** conve
2ee90 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61  rsion automatica
2eea0 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c  lly.  ^(The foll
2eeb0 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
2eec0 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
2eed0 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
2eee0 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
2eef0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
2ef00 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
2ef10 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
2ef20 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
2ef30 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
2ef40 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
2ef50 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
2ef60 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2ef70 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2ef80 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
2ef90 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2efa0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2efb0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2efc0 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
2efd0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2efe0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
2eff0 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
2f000 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
2f010 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2f020 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2f030 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c   Result is a NUL
2f040 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
2f050 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2f060 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2f070 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
2f080 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
2f090 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2f0a0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
2f0b0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2f0c0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2f0d0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
2f0e0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2f0f0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2f100 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
2f110 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
2f120 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2f130 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2f140 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
2f150 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
2f160 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
2f170 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2f180 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2f190 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
2f1a0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2f1b0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2f1c0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42  > [CAST] to BLOB
2f1d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2f1e0 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
2f1f0 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
2f200 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
2f210 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2f220 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2f230 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
2f240 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
2f250 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
2f260 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
2f270 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
2f280 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2f290 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2f2a0 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
2f2b0 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  R.** <tr><td>  B
2f2c0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
2f2d0 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  AT    <td> [CAST
2f2e0 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72  ] to REAL.** <tr
2f2f0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2f300 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2f310 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
2f320 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
2f330 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
2f340 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
2f350 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ^.**.** The tabl
2f360 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
2f370 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
2f380 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
2f390 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
2f3a0 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
2f3b0 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
2f3c0 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
2f3d0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
2f3e0 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
2f3f0 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
2f400 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
2f410 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
2f420 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
2f430 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
2f440 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
2f450 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
2f460 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
2f470 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
2f480 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
2f490 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
2f4a0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
2f4b0 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
2f4c0 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
2f4d0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2f4e0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2f4f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f500 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
2f510 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2f520 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
2f530 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
2f540 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
2f550 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
2f560 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
2f570 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
2f580 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
2f590 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2f5a0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
2f5b0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
2f5c0 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
2f5d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
2f5e0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2f5f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2f600 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
2f610 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
2f620 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
2f630 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
2f640 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
2f650 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2f660 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2f670 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
2f680 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f690 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
2f6a0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2f6b0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
2f6c0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2f6d0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2f6e0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2f6f0 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
2f700 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
2f710 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
2f720 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
2f730 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f740 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
2f750 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f760 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
2f770 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
2f780 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
2f790 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
2f7a0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
2f7b0 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e  *.** ^Conversion
2f7c0 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
2f7d0 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
2f7e0 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
2f7f0 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
2f800 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
2f810 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
2f820 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
2f830 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
2f840 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
2f850 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
2f860 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63  pointer referenc
2f870 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  es will have bee
2f880 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
2f890 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
2f8a0 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
2f8b0 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
2f8c0 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
2f8d0 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
2f8e0 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
2f8f0 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
2f900 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
2f910 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
2f920 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
2f930 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20   The safest and 
2f940 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
2f950 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
2f960 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
2f970 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
2f980 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
2f990 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
2f9a0 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
2f9b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2f9c0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2f9d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f9e0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
2f9f0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2fa00 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
2fa10 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2fa20 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
2fa30 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2fa40 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
2fa50 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2fa60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2fa70 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
2fa80 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
2fa90 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
2faa0 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
2fab0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
2fac0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2fad0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
2fae0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2faf0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
2fb00 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
2fb10 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
2fb20 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
2fb30 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
2fb40 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
2fb50 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2fb60 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
2fb70 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
2fb80 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
2fb90 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
2fba0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2fbb0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
2fbc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2fbd0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
2fbe0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2fbf0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
2fc00 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
2fc10 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2fc20 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
2fc30 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
2fc40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2fc50 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
2fc60 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2fc70 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
2fc80 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
2fc90 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
2fca0 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
2fcb0 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
2fcc0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2fcd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2fce0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2fcf0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
2fd00 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
2fd10 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
2fd20 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
2fd30 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
2fd40 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
2fd50 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
2fd60 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
2fd70 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
2fd80 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
2fd90 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
2fda0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2fdb0 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
2fdc0 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
2fdd0 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
2fde0 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
2fdf0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
2fe00 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
2fe10 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
2fe20 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
2fe30 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
2fe40 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
2fe50 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
2fe60 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
2fe70 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
2fe80 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
2fe90 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
2fea0 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
2feb0 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
2fec0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
2fed0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
2fee0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
2fef0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
2ff00 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )^.*/.const void
2ff10 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2ff20 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2ff30 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2ff40 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2ff50 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
2ff60 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2ff70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2ff80 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
2ff90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ffa0 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
2ffb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
2ffc0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2ffd0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2ffe0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2fff0 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
30000 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
30010 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
30020 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
30030 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
30040 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
30050 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
30060 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
30070 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
30080 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
30090 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
300a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
300b0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
300c0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
300d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
300e0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
300f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
30100 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
30110 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
30120 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
30130 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
30140 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
30150 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
30160 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
30170 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
30180 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
30190 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
301a0 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
301b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
301c0 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
301d0 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
301e0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
301f0 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
30200 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  ed no errors.** 
30210 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
30220 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
30230 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
30240 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
30250 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
30260 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
30270 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
30280 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
30290 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
302a0 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
302b0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
302c0 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
302d0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
302e0 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
302f0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
30300 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30310 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
30320 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
30330 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
30340 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
30350 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
30360 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30370 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
30380 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
30390 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
303a0 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
303b0 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
303c0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
303d0 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
303e0 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
303f0 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
30400 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
30410 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
30420 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
30430 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
30440 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
30450 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30460 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
30470 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
30480 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
30490 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
304a0 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
304b0 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
304c0 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
304d0 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
304e0 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
304f0 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
30500 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
30510 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
30520 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
30530 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
30540 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
30550 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
30560 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
30570 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
30580 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
30590 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
305a0 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
305b0 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
305c0 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
305d0 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
305e0 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
305f0 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  uption..*/.int s
30600 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
30610 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
30620 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
30630 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
30640 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
30650 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
30660 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
30670 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
30680 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
30690 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
306a0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
306b0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
306c0 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
306d0 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
306e0 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
306f0 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
30700 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
30710 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
30720 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
30730 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
30740 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
30750 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
30760 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
30770 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
30780 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
30790 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
307a0 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
307b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
307c0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
307d0 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
307e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
307f0 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
30800 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
30810 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
30820 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
30830 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
30840 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
30850 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
30860 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
30870 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
30880 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
30890 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
308a0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
308b0 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
308c0 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
308d0 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
308e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
308f0 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
30900 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
30910 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
30920 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
30930 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
30940 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
30950 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
30960 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
30970 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
30980 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
30990 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
309a0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
309b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
309c0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
309d0 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
309e0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
309f0 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
30a00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
30a10 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
30a20 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
30a30 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
30a40 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
30a50 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
30a60 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
30a70 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
30a80 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
30a90 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
30aa0 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
30ab0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
30ac0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
30ad0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30ae0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
30af0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
30b00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30b10 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
30b20 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  }.**.** ^These f
30b30 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
30b40 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
30b50 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
30b60 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
30b70 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
30b80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
30b90 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
30ba0 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
30bb0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
30bc0 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
30bd0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
30be0 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
30bf0 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65  ifferences betwe
30c00 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  en.** these rout
30c10 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78  ines are the tex
30c20 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63  t encoding expec
30c30 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73  ted for.** the s
30c40 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
30c50 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  (the name of the
30c60 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20   function being 
30c70 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20  created).** and 
30c80 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20  the presence or 
30c90 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73  absence of a des
30ca0 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
30cb0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c   for.** the appl
30cc0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
30cd0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
30ce0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
30cf0 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
30d00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
30d10 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
30d20 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
30d30 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20   be added.  ^If 
30d40 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
30d50 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
30d60 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
30d70 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70  nnection then ap
30d80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30d90 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
30da0 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a  must be added.**
30db0 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
30dc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70  e connection sep
30dd0 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  arately..**.** ^
30de0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
30df0 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
30e00 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
30e10 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74  tion to be creat
30e20 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e  ed or.** redefin
30e30 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68  ed.  ^The length
30e40 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
30e50 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
30e60 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a  ytes in a UTF-8.
30e70 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ** representatio
30e80 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  n, exclusive of 
30e90 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
30ea0 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74  tor.  ^Note that
30eb0 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e   the name.** len
30ec0 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
30ed0 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74  UTF-8 bytes, not
30ee0 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20   characters nor 
30ef0 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a  UTF-16 bytes.  .
30f00 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20  ** ^Any attempt 
30f10 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
30f20 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
30f30 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
30f40 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
30f50 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20  E_MISUSE] being 
30f60 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
30f70 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
30f80 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69  eter (nArg).** i
30f90 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
30fa0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
30fb0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
30fc0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
30fd0 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20  takes. ^If this 
30fe0 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c  parameter is -1,
30ff0 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
31000 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
31010 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
31020 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
31030 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20  guments between 
31040 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a  0 and the limit.
31050 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74  ** set by [sqlit
31060 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
31070 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
31080 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20  _ARG]).  If the 
31090 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
310a0 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
310b0 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
310c0 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20  an 127 then the 
310d0 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75  behavior is.** u
310e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
310f0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
31100 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
31110 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
31120 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
31130 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
31140 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
31150 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
31160 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
31170 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
31180 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68  on should set th
31190 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  is parameter to.
311a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
311b0 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74  LE] if the funct
311c0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
311d0 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b  on invokes .** [
311e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
311f0 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16le()] on an 
31200 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54  input, or [SQLIT
31210 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 68  E_UTF16BE] if th
31220 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
31230 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c  ion invokes [sql
31240 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
31250 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70  6be()] on an inp
31260 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  ut, or.** [SQLIT
31270 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c  E_UTF16] if [sql
31280 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
31290 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72  6()] is used, or
312a0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a   [SQLITE_UTF8].*
312b0 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54  * otherwise.  ^T
312c0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
312d0 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
312e0 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  stered multiple 
312f0 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64  times using.** d
31300 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 72  ifferent preferr
31310 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
31320 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  s, with differen
31330 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
31340 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e  s for.** each en
31350 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e  coding..** ^When
31360 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
31370 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
31380 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
31390 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
313a0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
313b0 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
313c0 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
313d0 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
313e0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
313f0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
31400 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74  arameter may opt
31410 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20  ionally be ORed 
31420 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54  with [SQLITE_DET
31430 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74  ERMINISTIC].** t
31440 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68  o signal that th
31450 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  e function will 
31460 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
31470 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69  e same result gi
31480 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ven.** the same 
31490 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 20  inputs within a 
314a0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
314b0 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20  ment.  Most SQL 
314c0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a  functions are.**
314d0 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20   deterministic. 
314e0 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72   The built-in [r
314f0 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e  andom()] SQL fun
31500 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d  ction is an exam
31510 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63  ple of a.** func
31520 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74  tion that is not
31530 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20   deterministic. 
31540 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 72   The SQLite quer
31550 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c  y planner is abl
31560 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20  e to.** perform 
31570 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d  additional optim
31580 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65  izations on dete
31590 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69  rministic functi
315a0 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f  ons, so use.** o
315b0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45  f the [SQLITE_DE
315c0 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61  TERMINISTIC] fla
315d0 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  g is recommended
315e0 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e   where possible.
315f0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66  .**.** ^(The fif
31600 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
31610 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
31620 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
31630 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
31640 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
31650 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
31660 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
31670 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
31680 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  _data()].)^.**.*
31690 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65  * ^The sixth, se
316a0 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68  venth and eighth
316b0 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
316c0 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
316d0 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
316e0 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
316f0 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
31700 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
31710 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
31720 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e  .** aggregate. ^
31730 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
31740 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
31750 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
31760 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
31770 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20   callback only; 
31780 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75  NULL pointers mu
31790 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
317a0 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
317b0 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
317c0 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74  rs. ^An aggregat
317d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
317e0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
317f0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
31800 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
31810 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   and NULL pointe
31820 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  r must be passed
31830 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20   for xFunc. ^To 
31840 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
31850 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
31860 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
31870 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74   pass NULL point
31880 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ers for all thre
31890 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  e function.** ca
318a0 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e  llbacks..**.** ^
318b0 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61  (If the ninth pa
318c0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
318d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
318e0 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e  on_v2() is not N
318f0 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  ULL,.** then it 
31900 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f  is destructor fo
31910 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
31920 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  n data pointer. 
31930 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74  .** The destruct
31940 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  or is invoked wh
31950 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
31960 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68  is deleted, eith
31970 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f  er by being.** o
31980 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65  verloaded or whe
31990 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
319a0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
319b0 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74  .)^.** ^The dest
319c0 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69  ructor is also i
319d0 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61  nvoked if the ca
319e0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
319f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31a00 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  _v2() fails..** 
31a10 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75  ^When the destru
31a20 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ctor callback of
31a30 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d   the tenth param
31a40 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c  eter is invoked,
31a50 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64   it.** is passed
31a60 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
31a70 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f  nt which is a co
31a80 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  py of the applic
31a90 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70  ation data .** p
31aa0 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
31ab0 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   the fifth param
31ac0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
31ad0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
31ae0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  v2()..**.** ^It 
31af0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
31b00 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
31b10 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
31b20 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
31b30 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
31b40 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
31b50 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
31b60 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
31b70 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
31b80 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
31b90 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
31ba0 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20  dings.  ^SQLite 
31bb0 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
31bc0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
31bd0 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  hat most closely
31be0 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
31bf0 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
31c00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
31c10 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74   used.  ^A funct
31c20 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
31c30 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
31c40 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
31c50 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
31c60 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
31c70 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
31c80 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
31c90 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
31ca0 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  g.  ^A function 
31cb0 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
31cc0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
31cd0 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
31ce0 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
31cf0 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
31d00 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
31d10 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
31d20 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
31d30 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41  fferent.  .** ^A
31d40 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
31d50 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
31d60 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
31d70 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
31d80 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
31d90 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
31da0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
31db0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
31dc0 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
31dd0 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
31de0 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42   UTF16..**.** ^B
31df0 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
31e00 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
31e10 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
31e20 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
31e30 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
31e40 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ^An application-
31e50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
31e60 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
31e70 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
31e80 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
31e90 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
31ea0 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
31eb0 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
31ec0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31ed0 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
31ee0 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
31ef0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
31f00 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
31f10 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
31f20 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  g..*/.int sqlite
31f30 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31f40 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
31f50 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
31f60 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
31f70 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
31f80 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
31f90 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
31fa0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
31fb0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
31fc0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
31fd0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
31fe0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31ff0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
32000 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
32010 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
32020 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
32030 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32040 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
32050 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
32060 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
32070 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
32080 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
32090 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
320a0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
320b0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
320c0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
320d0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
320e0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
320f0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
32100 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
32110 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
32120 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32130 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
32140 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
32150 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  n_v2(.  sqlite3 
32160 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
32170 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
32180 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
32190 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
321a0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
321b0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
321c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
321d0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
321e0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
321f0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
32200 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
32210 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
32220 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
32230 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20  e3_context*),.  
32240 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
32250 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
32260 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
32270 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20  Encodings.**.** 
32280 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
32290 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
322a0 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
322b0 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
322c0 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
322d0 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
322e0 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
322f0 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
32300 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
32310 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
32320 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
32330 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
32340 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
32350 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
32360 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
32370 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
32380 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
32390 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
323a0 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65        5    /* De
323b0 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66  precated */.#def
323c0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
323d0 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
323e0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
323f0 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
32400 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
32410 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61  EF: Function Fla
32420 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
32430 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20  onstants may be 
32440 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 69  ORed together wi
32450 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
32460 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72  TE_UTF8 | prefer
32470 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
32480 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  g] as the fourth
32490 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
324a0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
324b0 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  function()], [sq
324c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
324d0 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ction16()], or.*
324e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
324f0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d  e_function_v2()]
32500 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
32510 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
32520 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a  C    0x800../*.*
32530 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
32540 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
32550 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
32560 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
32570 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
32580 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
32590 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
325a0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
325b0 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
325c0 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
325d0 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
325e0 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
325f0 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
32600 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
32610 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
32620 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
32630 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
32640 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65  o help encourage
32650 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64   people to avoid
32660 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20  .** using these 
32670 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72  functions, we ar
32680 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74  e not going to t
32690 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65  ell you what the
326a0 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
326b0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
326c0 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44  RECATED.SQLITE_D
326d0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
326e0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
326f0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
32700 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
32710 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
32720 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
32730 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
32740 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
32750 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
32760 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
32770 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
32780 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
32790 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
327a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
327b0 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
327c0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
327d0 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
327e0 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
327f0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
32800 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
32810 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
32820 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
32830 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
32840 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  t),.            
32850 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c            void*,
32860 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
32870 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
32880 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
32890 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
328a0 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
328b0 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
328c0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
328d0 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
328e0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
328f0 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
32900 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
32910 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
32920 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
32930 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
32940 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
32950 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
32960 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
32970 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
32980 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
32990 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
329a0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
329b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
329c0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
329d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
329e0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
329f0 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
32a00 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
32a10 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
32a20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
32a30 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  ** The 3rd param
32a40 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
32a50 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
32a60 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
32a70 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
32a80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
32a90 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
32aa0 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
32ab0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
32ac0 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
32ad0 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
32ae0 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
32af0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
32b00 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
32b10 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
32b20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
32b30 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
32b40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
32b50 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
32b60 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
32b70 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
32b80 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
32b90 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
32ba0 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
32bb0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
32bc0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
32bd0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
32be0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
32bf0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
32c00 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
32c10 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
32c20 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
32c30 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
32c40 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
32c50 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
32c60 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
32c70 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
32c80 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
32c90 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
32ca0 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
32cb0 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
32cc0 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
32cd0 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
32ce0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
32cf0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
32d00 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
32d10 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
32d20 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
32d30 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
32d40 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
32d50 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
32d60 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
32d70 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
32d80 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
32d90 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
32da0 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74  xtract UTF-16 st
32db0 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
32dc0 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
32dd0 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
32de0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
32df0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
32e00 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
32e10 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
32e20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
32e30 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
32e40 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
32e50 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
32e60 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
32e70 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
32e80 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
32e90 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
32ea0 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
32eb0 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
32ec0 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
32ed0 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
32ee0 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
32ef0 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
32f00 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
32f10 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
32f20 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
32f30 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
32f40 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
32f50 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
32f60 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
32f70 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
32f80 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
32f90 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
32fa0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
32fb0 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50  urned.)^.**.** P
32fc0 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
32fd0 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
32fe0 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
32ff0 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
33000 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
33010 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
33020 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
33030 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
33040 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
33050 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
33060 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
33070 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
33080 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
33090 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
330a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
330b0 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
330c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
330d0 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
330e0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
330f0 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
33100 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
33110 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
33120 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
33130 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
33140 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
33150 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
33160 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
33170 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ers..*/.const vo
33180 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
33190 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
331a0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
331b0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
331c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
331d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
331e0 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
331f0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
33200 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
33210 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
33220 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
33230 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
33240 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33250 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
33260 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
33270 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
33280 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
33290 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
332a0 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
332b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
332c0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
332d0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
332e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
332f0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
33300 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
33310 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
33320 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
33330 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33340 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
33350 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
33360 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
33370 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
33380 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
33390 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
333a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
333b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
333c0 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
333d0 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
333e0 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74  .**.** Implement
333f0 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67  ations of aggreg
33400 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
33410 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f  s use this.** ro
33420 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
33430 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f  e memory for sto
33440 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
33450 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
33460 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
33470 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
33480 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
33490 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a  ne is called .**
334a0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
334b0 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  r aggregate func
334c0 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  tion, SQLite.** 
334d0 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d  allocates N of m
334e0 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
334f0 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  t that memory, a
33500 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
33510 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e  nter.** to the n
33520 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73  ew memory. ^On s
33530 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
33540 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
33550 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
33560 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
33570 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
33580 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
33590 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61  tance,.** the sa
335a0 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
335b0 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f  urned.  Sqlite3_
335c0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
335d0 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a  t() is normally.
335e0 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66  ** called once f
335f0 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  or each invocati
33600 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20  on of the xStep 
33610 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65  callback and the
33620 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69  n one.** last ti
33630 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e  me when the xFin
33640 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  al callback is i
33650 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20  nvoked.  ^(When 
33660 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a  no rows match.**
33670 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75   an aggregate qu
33680 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29  ery, the xStep()
33690 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
336a0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
336b0 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
336c0 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63  ation is never c
336d0 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c  alled and xFinal
336e0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61  () is called exa
336f0 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e  ctly once..** In
33700 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71   those cases, sq
33710 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33720 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20  context() might 
33730 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  be called for th
33740 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20  e.** first time 
33750 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e  from within xFin
33760 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  al().)^.**.** ^T
33770 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
33780 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
33790 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
337a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
337b0 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20   .** when first 
337c0 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c  called if N is l
337d0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
337e0 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20  l to zero or if 
337f0 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  a memory.** allo
33800 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
33810 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
33820 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
33830 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
33840 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
33850 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
33860 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
33870 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
33880 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
33890 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
338a0 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
338b0 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
338c0 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
338d0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
338e0 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
338f0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
33900 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
33910 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
33920 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
33930 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
33940 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46  ^  Within the xF
33950 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69  inal callback, i
33960 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74  t is customary t
33970 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20  o set.** N=0 in 
33980 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
33990 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
339a0 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20  xt(C,N) so that 
339b0 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73  no .** pointless
339c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
339d0 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a  ons occur..**.**
339e0 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74   ^SQLite automat
339f0 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
33a00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
33a10 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
33a20 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
33a30 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67  xt() when the ag
33a40 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f  gregate query co
33a50 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
33a60 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
33a70 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70  er must be a cop
33a80 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  y of the.** [sql
33a90 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
33aa0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
33ab0 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
33ac0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
33ad0 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70  .** to the xStep
33ae0 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
33af0 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
33b00 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
33b10 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
33b20 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
33b30 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
33b40 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
33b50 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
33b60 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
33b70 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
33b80 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
33b90 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
33ba0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
33bb0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
33bc0 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73  ext*, int nBytes
33bd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33be0 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f  EF: User Data Fo
33bf0 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
33c00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
33c10 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
33c20 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
33c30 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
33c40 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
33c50 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
33c60 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
33c70 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
33c80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
33c90 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
33ca0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
33cb0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33cc0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
33cd0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
33ce0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
33cf0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
33d00 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
33d10 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
33d20 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
33d30 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
33d40 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
33d50 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
33d60 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
33d70 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
33d80 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
33d90 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
33da0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
33db0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
33dc0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
33dd0 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  n For Functions.
33de0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33df0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
33e00 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
33e10 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
33e20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
33e30 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
33e40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
33e50 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
33e60 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
33e70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33e80 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
33e90 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33ea0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
33eb0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
33ec0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
33ed0 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
33ee0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
33ef0 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65  ction..*/.sqlite
33f00 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
33f10 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
33f20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
33f30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33f40 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
33f50 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54  ary Data.**.** T
33f60 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d  hese functions m
33f70 61 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e  ay be used by (n
33f80 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51  on-aggregate) SQ
33f90 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
33fa0 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
33fb0 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
33fc0 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
33fd0 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
33fe0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
33ff0 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
34000 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
34010 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
34020 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
34030 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
34040 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
34050 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
34060 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72  tadata may be pr
34070 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61  eserved.  An exa
34080 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65  mple.** of where
34090 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75   this might be u
340a0 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65  seful is in a re
340b0 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
340c0 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e   matching.** fun
340d0 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
340e0 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
340f0 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
34100 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f  ssion can be sto
34110 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
34120 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
34130 74 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 73  th the pattern s
34140 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e  tring.  .** Then
34150 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
34160 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72  pattern string r
34170 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c  emains the same,
34180 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  .** the compiled
34190 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
341a0 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
341b0 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
341c0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
341d0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
341e0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
341f0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
34200 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
34210 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
34220 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
34230 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
34240 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
34250 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
34260 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
34270 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
34280 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
34290 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
342a0 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72  nction. ^If ther
342b0 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61  e is no metadata
342c0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
342d0 69 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ith the function
342e0 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20   argument, this 
342f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
34300 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ata() interface.
34310 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ** returns a NUL
34320 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
34330 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65   ^The sqlite3_se
34340 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
34350 58 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76  X) interface sav
34360 65 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 61  es P as metadata
34370 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
34380 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
34390 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
343a0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
343b0 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63  ^Subsequent.** c
343c0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
343d0 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29  get_auxdata(C,N)
343e0 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74   return P from t
343f0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
34400 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
34410 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63  xdata(C,N,P,X) c
34420 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64  all if the metad
34430 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c  ata is still val
34440 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66  id or.** NULL if
34450 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 61   the metadata ha
34460 73 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 64  s been discarded
34470 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68  ..** ^After each
34480 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
34490 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
344a0 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 73  ,P,X) where X is
344b0 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51   not NULL,.** SQ
344c0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
344d0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
344e0 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20  function X with 
344f0 70 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 63  parameter P exac
34500 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65  tly.** once, whe
34510 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  n the metadata i
34520 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  s discarded..** 
34530 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
34540 6f 20 64 69 73 63 61 72 64 20 74 68 65 20 6d 65  o discard the me
34550 74 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 69  tadata at any ti
34560 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c  me, including: <
34570 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e  ul>.** <li> when
34580 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
34590 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
345a0 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f  meter changes, o
345b0 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b  r.** <li> when [
345c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
345d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
345e0 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
345f0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  ed for the.**   
34600 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74     SQL statement
34610 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  , or.** <li> whe
34620 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  n sqlite3_set_au
34630 78 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b  xdata() is invok
34640 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20  ed again on the 
34650 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  same parameter, 
34660 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e  or.** <li> durin
34670 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  g the original s
34680 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34690 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61  ta() call when a
346a0 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20   memory .**     
346b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
346c0 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29  r occurs. </ul>)
346d0 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65  ^.**.** Note the
346e0 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20   last bullet in 
346f0 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65  particular.  The
34700 20 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e   destructor X in
34710 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74   .** sqlite3_set
34720 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
34730 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
34740 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  d immediately, b
34750 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c  efore the.** sql
34760 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
34770 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 65  () interface eve
34780 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63  n returns.  Henc
34790 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
347a0 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c  xdata().** shoul
347b0 64 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72  d be called near
347c0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
347d0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
347e0 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a  ntation and the.
347f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ** function impl
34800 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
34810 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75  d not make any u
34820 73 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a  se of P after.**
34830 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
34840 64 61 74 61 28 29 20 68 61 73 20 62 65 65 6e 20  data() has been 
34850 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  called..**.** ^(
34860 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
34870 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
34880 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
34890 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
348a0 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
348b0 74 65 72 73 20 74 68 61 74 20 61 72 65 20 63 6f  ters that are co
348c0 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74  mpile-time const
348d0 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ants, including 
348e0 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
348f0 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72  s and [parameter
34900 73 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f  s] and expressio
34910 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d  ns composed from
34920 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a   the same.)^.**.
34930 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
34940 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
34950 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
34960 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
34970 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
34980 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
34990 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
349a0 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
349b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
349c0 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t N);.void sqlit
349d0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73  e3_set_auxdata(s
349e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
349f0 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76   int N, void*, v
34a00 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
34a10 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
34a20 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
34a30 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
34a40 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
34a50 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  r.**.** These ar
34a60 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73  e special values
34a70 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
34a80 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
34a90 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
34aa0 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
34ab0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
34ac0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
34ad0 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68  blob()].  ^If th
34ae0 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
34af0 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49  argument is SQLI
34b00 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65  TE_STATIC, it me
34b10 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
34b20 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20  tent pointer is 
34b30 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20  constant.** and 
34b40 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67  will never chang
34b50 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20  e.  It does not 
34b60 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72  need to be destr
34b70 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53  oyed.  ^The.** S
34b80 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
34b90 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
34ba0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
34bb0 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
34bc0 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
34bd0 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
34be0 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
34bf0 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
34c00 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
34c10 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
34c20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
34c30 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
34c40 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
34c50 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
34c60 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
34c70 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a  C++ compilers..*
34c80 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
34c90 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
34ca0 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
34cb0 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
34cc0 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
34cd0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
34ce0 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
34cf0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
34d00 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
34d10 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
34d20 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
34d30 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
34d40 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
34d50 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
34d60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
34d70 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
34d80 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
34d90 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
34da0 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
34db0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
34dc0 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
34dd0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34de0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
34df0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34e00 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
34e10 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
34e20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
34e30 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
34e40 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
34e50 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
34e60 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
34e70 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
34e80 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
34e90 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
34ea0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
34eb0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
34ec0 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
34ed0 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
34ee0 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
34ef0 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
34f00 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
34f10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34f20 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
34f30 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
34f40 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
34f50 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
34f60 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34f70 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
34f80 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
34f90 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
34fa0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
34fb0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
34fc0 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
34fd0 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
34fe0 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
34ff0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
35000 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35010 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
35020 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
35030 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
35040 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35050 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
35060 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
35070 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
35080 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
35090 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
350a0 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
350b0 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
350c0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
350d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
350e0 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
350f0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
35100 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
35110 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35120 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
35130 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
35140 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
35150 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
35160 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
35170 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
35180 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
35190 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
351a0 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
351b0 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
351c0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
351d0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
351e0 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
351f0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
35200 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
35210 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
35220 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
35230 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35240 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
35250 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
35260 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
35270 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
35280 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
35290 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
352a0 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
352b0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
352c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
352d0 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
352e0 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
352f0 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
35300 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
35310 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
35320 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
35330 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
35340 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
35350 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
35360 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35370 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
35380 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
35390 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
353a0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
353b0 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
353c0 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
353d0 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
353e0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
353f0 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
35400 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
35410 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
35420 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
35430 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35440 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
35450 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
35460 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
35470 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
35480 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
35490 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
354a0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
354b0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
354c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
354d0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
354e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
354f0 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
35500 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
35510 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
35520 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
35530 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
35540 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
35550 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
35560 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
35570 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
35580 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
35590 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
355a0 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
355b0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
355c0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
355d0 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
355e0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
355f0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
35600 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
35610 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
35620 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
35630 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
35640 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
35650 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
35660 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
35670 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
35680 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
35690 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
356a0 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
356b0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
356c0 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
356d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
356e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
356f0 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72  r_toobig() inter
35700 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
35710 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
35720 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
35730 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
35740 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20   or BLOB is too 
35750 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
35760 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
35770 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35780 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  or_nomem() inter
35790 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
357a0 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
357b0 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
357c0 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
357d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
357e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
357f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
35800 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
35810 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
35820 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
35830 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35840 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
35850 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
35860 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
35870 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
35880 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
35890 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
358a0 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
358b0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
358c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
358d0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
358e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
358f0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
35900 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
35910 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
35920 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
35930 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
35940 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35950 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
35960 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
35970 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
35980 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
35990 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
359a0 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
359b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
359c0 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
359d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
359e0 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
359f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35a00 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
35a10 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
35a20 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
35a30 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
35a40 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
35a50 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35a60 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
35a70 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
35a80 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
35a90 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
35aa0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
35ab0 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
35ac0 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
35ad0 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
35ae0 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
35af0 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20  tively..** ^The 
35b00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35b10 65 78 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  ext64() interfac
35b20 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
35b30 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a  n value of an.**
35b40 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35b50 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
35b60 20 62 65 20 61 20 74 65 78 74 20 73 74 72 69 6e   be a text strin
35b70 67 20 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67  g in an encoding
35b80 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62 79  .** specified by
35b90 20 74 68 65 20 66 69 66 74 68 20 28 61 6e 64 20   the fifth (and 
35ba0 6c 61 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c  last) parameter,
35bb0 20 77 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f   which must be o
35bc0 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45  ne.** of [SQLITE
35bd0 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
35be0 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f  UTF16], [SQLITE_
35bf0 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
35c00 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a  LITE_UTF16LE]..*
35c10 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20  * ^SQLite takes 
35c20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
35c30 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
35c40 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
35c50 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
35c60 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
35c70 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
35c80 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  faces..** ^If th
35c90 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
35ca0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
35cb0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
35cc0 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67  rfaces.** is neg
35cd0 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69  ative, then SQLi
35ce0 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20  te takes result 
35cf0 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e  text from the 2n
35d00 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
35d10 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
35d20 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
35d30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
35d40 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
35d50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35d60 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
35d70 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
35d80 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
35d90 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
35da0 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
35db0 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
35dc0 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
35dd0 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
35de0 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
35df0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
35e00 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
35e10 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72    If the 3rd par
35e20 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65  ameter is non-ne
35e30 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a  gative, then it.
35e40 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  ** must be the b
35e50 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20  yte offset into 
35e60 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
35e70 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
35e80 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70  tor would.** app
35e90 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e  ear if the strin
35ea0 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d  g where NUL term
35eb0 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
35ec0 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
35ed0 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73  ccur.** in the s
35ee0 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20  tring at a byte 
35ef0 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c  offset that is l
35f00 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c  ess than the val
35f10 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a  ue of the 3rd.**
35f20 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
35f30 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
35f40 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61  tring will conta
35f50 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
35f60 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75   and the.** resu
35f70 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
35f80 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73  s operating on s
35f90 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65  trings with embe
35fa0 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
35fb0 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  efined..** ^If t
35fc0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
35fd0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
35fe0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
35ff0 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
36000 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
36010 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  b is a non-NULL 
36020 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
36030 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a  Lite calls that.
36040 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74  ** function as t
36050 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e  he destructor on
36060 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
36070 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74  B result when it
36080 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64   has.** finished
36090 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
360a0 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
360b0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
360c0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
360d0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
360e0 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c  ces or to.** sql
360f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
36100 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
36110 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
36120 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c  STATIC, then SQL
36130 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74  ite.** assumes t
36140 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20  hat the text or 
36150 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69  BLOB result is i
36160 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65  n constant space
36170 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a   and does not.**
36180 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e   copy the conten
36190 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  t of the paramet
361a0 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65  er nor call a de
361b0 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
361c0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20  content.** when 
361d0 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
361e0 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
361f0 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
36200 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
36210 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36220 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
36230 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
36240 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
36250 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
36260 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e  tant SQLITE_TRAN
36270 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51  SIENT.** then SQ
36280 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
36290 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  y of the result 
362a0 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69  into space obtai
362b0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d  ned from.** from
362c0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
362d0 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65  ()] before it re
362e0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
362f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36300 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
36310 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
36320 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
36330 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36340 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
36350 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75  a copy the.** [u
36360 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
36370 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36380 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
36390 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
363a0 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
363b0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
363c0 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73   interface makes
363d0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
363e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
363f0 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73  * so that the [s
36400 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70  qlite3_value] sp
36410 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70  ecified in the p
36420 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61  arameter may cha
36430 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61  nge or.** be dea
36440 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73  llocated after s
36450 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
36460 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69  lue() returns wi
36470 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
36480 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  A [protected sql
36490 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
364a0 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65  ct may always be
364b0 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a   used where an.*
364c0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
364d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
364e0 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64  ject is required
364f0 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b  , so either.** k
36500 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ind of [sqlite3_
36510 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61  value] object ca
36520 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74  n be used with t
36530 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  his interface..*
36540 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f  *.** If these ro
36550 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
36560 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68  d from within th
36570 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  e different thre
36580 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f  ad.** than the o
36590 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ne containing th
365a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
365b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
365c0 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20  hat received.** 
365d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
365e0 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74  text] pointer, t
365f0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
36600 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69  ndefined..*/.voi
36610 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36620 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  _blob(sqlite3_co
36630 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
36640 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
36650 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
36660 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
36670 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  lob64(sqlite3_co
36680 6e 74 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f 69  ntext*,const voi
36690 64 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  d*,sqlite3_uint6
366a0 34 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  4,void(*)(void*)
366b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
366c0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
366d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
366e0 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
366f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36700 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
36710 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
36720 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
36730 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36740 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
36750 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
36760 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
36770 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36780 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
36790 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
367a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
367b0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
367c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
367d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
367e0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
367f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36800 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
36810 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
36820 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36830 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
36840 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
36850 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36860 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
36870 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36880 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
36890 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
368a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
368b0 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
368c0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
368d0 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
368e0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
368f0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36900 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f  _text64(sqlite3_
36910 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
36920 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
36930 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
36940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36950 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c   void(*)(void*),
36960 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65   unsigned char e
36970 6e 63 6f 64 69 6e 67 29 3b 0a 76 6f 69 64 20 73  ncoding);.void s
36980 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
36990 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
369a0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
369b0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
369c0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
369d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
369e0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
369f0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
36a00 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
36a10 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
36a20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
36a30 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
36a40 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
36a50 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
36a60 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
36a70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36a80 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
36a90 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
36aa0 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
36ab0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
36ac0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
36ad0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
36ae0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36af0 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
36b00 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a  ating Sequences.
36b10 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
36b20 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f  ctions add, remo
36b30 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20  ve, or modify a 
36b40 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f  [collation] asso
36b50 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
36b60 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
36b70 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
36b80 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
36b90 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
36ba0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
36bb0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20   collation is a 
36bc0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
36bd0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
36be0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
36bf0 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
36c00 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
36c10 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
36c20 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
36c30 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72  e byte order for
36c40 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36c50 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a  collation16()..*
36c60 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  * ^Collation nam
36c70 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20  es that compare 
36c80 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20  equal according 
36c90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e  to [sqlite3_strn
36ca0 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63  icmp()] are.** c
36cb0 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20  onsidered to be 
36cc0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a  the same name..*
36cd0 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64  *.** ^(The third
36ce0 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74   argument (eText
36cf0 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  Rep) must be one
36d00 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
36d10 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  s:.** <ul>.** <l
36d20 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  i> [SQLITE_UTF8]
36d30 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
36d40 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c  E_UTF16LE],.** <
36d50 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
36d60 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6BE],.** <li> [S
36d70 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72  QLITE_UTF16], or
36d80 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
36d90 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e  _UTF16_ALIGNED].
36da0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  .** </ul>)^.** ^
36db0 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  The eTextRep arg
36dc0 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73  ument determines
36dd0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
36de0 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a   strings passed.
36df0 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ** to the collat
36e00 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
36e10 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b  lback, xCallback
36e20 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
36e30 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51  E_UTF16] and [SQ
36e40 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
36e50 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65  ED] values for e
36e60 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65  TextRep.** force
36e70 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55   strings to be U
36e80 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65  TF16 with native
36e90 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
36ea0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  ^The [SQLITE_UTF
36eb0 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
36ec0 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66  e for eTextRep f
36ed0 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f  orces strings to
36ee0 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20   begin.** on an 
36ef0 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73  even byte addres
36f00 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  s..**.** ^The fo
36f10 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70  urth argument, p
36f20 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69  Arg, is an appli
36f30 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
36f40 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73  ter that is pass
36f50 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73  ed.** through as
36f60 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
36f70 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ent to the colla
36f80 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
36f90 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
36fa0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
36fb0 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73  t, xCallback, is
36fc0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
36fd0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
36fe0 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70  tion..** ^Multip
36ff0 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  le collating fun
37000 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65  ctions can be re
37010 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
37020 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
37030 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65  .** with differe
37040 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61  nt eTextRep para
37050 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74  meters and SQLit
37060 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68  e will use which
37070 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ever.** function
37080 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65   requires the le
37090 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
370a0 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f  ta transformatio
370b0 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43  n..** ^If the xC
370c0 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
370d0 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
370e0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
370f0 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74  tion is.** delet
37100 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63  ed.  ^When all c
37110 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
37120 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61  ns having the sa
37130 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65  me name are dele
37140 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c  ted,.** that col
37150 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e  lation is no lon
37160 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a  ger usable..**.*
37170 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  * ^The collating
37180 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
37190 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
371a0 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  th a copy of the
371b0 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63   pArg .** applic
371c0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
371d0 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20  er and with two 
371e0 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65  strings in the e
371f0 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
37200 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78  d.** by the eTex
37210 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20  tRep argument.  
37220 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
37230 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75  nction must retu
37240 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  rn an.** integer
37250 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76   that is negativ
37260 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69  e, zero, or posi
37270 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66  tive.** if the f
37280 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c  irst string is l
37290 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20  ess than, equal 
372a0 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
372b0 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a  han the second,.
372c0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
372d0 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75    A collating fu
372e0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61  nction must alwa
372f0 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61  ys return the sa
37300 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76  me answer.** giv
37310 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75  en the same inpu
37320 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d  ts.  If two or m
37330 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ore collating fu
37340 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69  nctions are regi
37350 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65  stered.** to the
37360 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20   same collation 
37370 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66  name (using diff
37380 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76  erent eTextRep v
37390 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a  alues) then all.
373a0 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20  ** must give an 
373b0 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65  equivalent answe
373c0 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77  r when invoked w
373d0 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73  ith equivalent s
373e0 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63  trings..** The c
373f0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
37400 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20  n must obey the 
37410 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72  following proper
37420 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20  ties for all.** 
37430 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e  strings A, B, an
37440 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  d C:.**.** <ol>.
37450 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
37460 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c  then B==A..** <l
37470 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42  i> If A==B and B
37480 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a  ==C then A==C..*
37490 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
374a0 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a   THEN B&gt;A..**
374b0 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
374c0 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20  and B&lt;C then 
374d0 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  A&lt;C..** </ol>
374e0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c  .**.** If a coll
374f0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66  ating function f
37500 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20  ails any of the 
37510 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74  above constraint
37520 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f  s and that.** co
37530 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37540 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20   is  registered 
37550 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74  and used, then t
37560 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  he behavior of S
37570 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65  QLite.** is unde
37580 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
37590 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
375a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
375b0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
375c0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
375d0 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68  ion().** with th
375e0 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  e addition that 
375f0 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  the xDestroy cal
37600 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
37610 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a   on pArg when.**
37620 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
37630 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
37640 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e  ed..** ^Collatin
37650 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
37660 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
37670 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
37680 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c   by later.** cal
37690 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
376a0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
376b0 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74  ctions or when t
376c0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
376d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
376e0 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
376f0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
37700 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72  *.** ^The xDestr
37710 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c  oy callback is <
37720 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64  u>not</u> called
37730 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69   if the .** sqli
37740 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37750 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69  tion_v2() functi
37760 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69  on fails.  Appli
37770 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76  cations that inv
37780 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  oke.** sqlite3_c
37790 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
377a0 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d  v2() with a non-
377b0 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72  NULL xDestroy ar
377c0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a  gument should .*
377d0 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  * check the retu
377e0 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70  rn code and disp
377f0 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ose of the appli
37800 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
37810 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65  ter.** themselve
37820 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78  s rather than ex
37830 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74  pecting SQLite t
37840 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66  o deal with it f
37850 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73  or them..** This
37860 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72   is different fr
37870 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53  om every other S
37880 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
37890 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65    The inconsiste
378a0 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72  ncy .** is unfor
378b0 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f  tunate but canno
378c0 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74  t be changed wit
378d0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61  hout breaking ba
378e0 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70  ckwards .** comp
378f0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
37900 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c   See also:  [sql
37910 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
37920 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71  eeded()] and [sq
37930 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
37940 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
37950 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
37960 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
37970 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
37980 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
37990 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
379a0 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
379b0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
379c0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
379d0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
379e0 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
379f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37a00 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
37a10 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
37a20 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
37a30 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
37a40 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
37a50 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
37a60 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
37a70 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
37a80 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
37a90 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
37aa0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
37ab0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
37ac0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
37ad0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
37ae0 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
37af0 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
37b00 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
37b10 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
37b20 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
37b30 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
37b40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37b50 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
37b60 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
37b70 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e   ^To avoid havin
37b80 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
37b90 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
37ba0 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
37bb0 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
37bc0 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
37bd0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
37be0 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
37bf0 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
37c00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37c10 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76  ction] to be inv
37c20 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
37c30 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
37c40 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
37c50 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
37c60 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63  .** ^If the func
37c70 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
37c80 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
37c90 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
37ca0 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
37cb0 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
37cc0 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
37cd0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
37ce0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
37cf0 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
37d00 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66  ed in UTF-8. ^If
37d10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
37d20 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
37d30 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
37d40 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
37d50 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
37d60 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
37d70 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c  order..** ^A cal
37d80 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63  l to either func
37d90 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68  tion replaces th
37da0 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61  e existing colla
37db0 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c  tion-needed call
37dc0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68  back..**.** ^(Wh
37dd0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
37de0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
37df0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
37e00 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
37e10 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
37e20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
37e30 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
37e40 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
37e50 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
37e60 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
37e70 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
37e80 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
37e90 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
37ea0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
37eb0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
37ec0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
37ed0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
37ee0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  * or [SQLITE_UTF
37ef0 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
37f00 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72  g the most desir
37f10 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
37f20 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
37f30 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
37f40 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66  required.  The f
37f50 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
37f60 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
37f70 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63  he.** required c
37f80 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
37f90 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  e.)^.**.** The c
37fa0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
37fb0 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
37fc0 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
37fd0 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
37fe0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
37ff0 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
38000 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
38010 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
38020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
38030 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
38040 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
38050 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
38060 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
38070 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
38080 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
38090 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
380a0 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
380b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
380c0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
380d0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
380e0 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
380f0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
38100 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
38110 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
38120 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41  #ifdef SQLITE_HA
38130 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70  S_CODEC./*.** Sp
38140 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
38150 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
38160 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
38170 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
38180 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
38190 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
381a0 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
381b0 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
381c0 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
381d0 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
381e0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
381f0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
38200 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
38210 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
38220 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
38230 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
38240 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
38250 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
38260 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
38270 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
38280 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
38290 5f 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74  _key_v2(.  sqlit
382a0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
382b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
382c0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
382d0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  yed */.  const c
382e0 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20  har *zDbName,   
382f0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
38300 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
38310 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
38320 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
38330 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
38340 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
38350 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
38360 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
38370 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
38380 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
38390 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
383a0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
383b0 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
383c0 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
383d0 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
383e0 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
383f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
38400 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
38410 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
38420 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
38430 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
38440 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
38450 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
38460 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
38470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38480 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
38490 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
384a0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
384b0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
384c0 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
384d0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
384e0 33 5f 72 65 6b 65 79 5f 76 32 28 0a 20 20 73 71  3_rekey_v2(.  sq
384f0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
38500 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
38510 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
38520 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
38530 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
38540 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61             /* Na
38550 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
38560 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  se */.  const vo
38570 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
38580 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
38590 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
385a0 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61  ** Specify the a
385b0 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f  ctivation key fo
385c0 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65  r a SEE database
385d0 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
385e0 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
385f0 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65   the SEE routine
38600 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
38610 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
38620 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e  ivate_see(.  con
38630 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
38640 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
38650 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
38660 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23   */.);.#endif..#
38670 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41  ifdef SQLITE_ENA
38680 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20  BLE_CEROD./*.** 
38690 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
386a0 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
386b0 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e   CEROD database.
386c0 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
386d0 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
386e0 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e  the CEROD routin
386f0 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
38700 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63  .void sqlite3_ac
38710 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20  tivate_cerod(.  
38720 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73  const char *zPas
38730 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f  sPhrase        /
38740 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72  * Activation phr
38750 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66  ase */.);.#endif
38760 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38770 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74  : Suspend Execut
38780 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
38790 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  Time.**.** The s
387a0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66  qlite3_sleep() f
387b0 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
387c0 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
387d0 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
387e0 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74  cution.** for at
387f0 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20   least a number 
38800 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
38810 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73  specified in its
38820 20 70 61 72 61 6d 65