/ Hex Artifact Content
Login

Artifact 86cddbfdb3155967858c1469108813bcc08eda21:


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 53 45 52  QLITE_CONFIG_SER
20c0: 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65  IALIZED].  ^(The
20d0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
20e0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
20f0: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
2100: 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79  ction shows only
2110: 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
2120: 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20  e setting of.** 
2130: 74 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e  thread safety, n
2140: 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20  ot any run-time 
2150: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20  changes to that 
2160: 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a  setting made by.
2170: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  ** sqlite3_confi
2180: 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  g(). In other wo
2190: 72 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20  rds, the return 
21a0: 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
21b0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a  e3_threadsafe().
21c0: 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20  ** is unchanged 
21d0: 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  by calls to sqli
21e0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a  te3_config().)^.
21f0: 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74  **.** See the [t
2200: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64  hreading mode] d
2210: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
2220: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2230: 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  rmation..*/.int 
2240: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2250: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  fe(void);../*.**
2260: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
2270: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48  ase Connection H
2280: 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44  andle.** KEYWORD
2290: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  S: {database con
22a0: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61  nection} {databa
22b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a  se connections}.
22c0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
22d0: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
22e0: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
22f0: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  y a pointer to a
2300: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a  n instance of.**
2310: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75   the opaque stru
2320: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c  cture named "sql
2330: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73  ite3".  It is us
2340: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66  eful to think of
2350: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70   an sqlite3.** p
2360: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a  ointer as an obj
2370: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ect.  The [sqlit
2380: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
2390: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
23a0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
23b0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
23c0: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f  faces are its co
23d0: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20  nstructors, and 
23e0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
23f0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2400: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72  3_close_v2()] ar
2410: 65 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72  e its destructor
2420: 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  s.  There are ma
2430: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65  ny other.** inte
2440: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
2450: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2460: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
2470: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2480: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
2490: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
24a0: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
24b0: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
24c0: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
24d0: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
24e0: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
24f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
2500: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
2510: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
2520: 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a  Integer Types.**
2530: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
2540: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  e_int64 sqlite_u
2550: 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61  int64.**.** Beca
2560: 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20  use there is no 
2570: 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77  cross-platform w
2580: 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34  ay to specify 64
2590: 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70  -bit integer typ
25a0: 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63  es.** SQLite inc
25b0: 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66  ludes typedefs f
25c0: 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  or 64-bit signed
25d0: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e   and unsigned in
25e0: 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  tegers..**.** Th
25f0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
2600: 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  and sqlite3_uint
2610: 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65  64 are the prefe
2620: 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69  rred type defini
2630: 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71  tions..** The sq
2640: 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73  lite_int64 and s
2650: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
2660: 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  es are supported
2670: 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a   for backwards.*
2680: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
2690: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  only..**.** ^The
26a0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
26b0: 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  nd sqlite_int64 
26c0: 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20  types can store 
26d0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a  integer values.*
26e0: 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33  * between -92233
26f0: 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61  72036854775808 a
2700: 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35  nd +922337203685
2710: 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76  4775807 inclusiv
2720: 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
2730: 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73  te3_uint64 and s
2740: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
2750: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2760: 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20  eger values .** 
2770: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31  between 0 and +1
2780: 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31  8446744073709551
2790: 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a  615 inclusive..*
27a0: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
27b0: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70  INT64_TYPE.  typ
27c0: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  edef SQLITE_INT6
27d0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e  4_TYPE sqlite_in
27e0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
27f0: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49  nsigned SQLITE_I
2800: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2810: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64  _uint64;.#elif d
2820: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2830: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2840: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2850: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2860: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2870: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2880: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2890: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
28a0: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
28b0: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
28c0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
28d0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
28e0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
28f0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2900: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2910: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2920: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2930: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2940: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2950: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2960: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2970: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2980: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2990: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
29a0: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
29b0: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
29c0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
29d0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
29e0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
29f0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2a00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2a10: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2a20: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
2a30: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2a40: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2a50: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2a60: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2a70: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2a80: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2a90: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2aa0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ab0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2ac0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2ad0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2ae0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2af0: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2b00: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2b10: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2b20: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2b30: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2b40: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2b50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b60: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2b70: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2b80: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2b90: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ba0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2bb0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2bc0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2bd0: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2be0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2bf0: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2c00: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2c10: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2c20: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2c30: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2c40: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2c50: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2c60: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2c70: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2c80: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2c90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ca0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2cb0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2cc0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
2cd0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
2ce0: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
2cf0: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
2d00: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2d10: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
2d20: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
2d30: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
2d40: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
2d50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2d60: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
2d70: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
2d80: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
2d90: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
2da0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
2db0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
2dc0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
2dd0: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
2de0: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
2df0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
2e00: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
2e10: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e20: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2e30: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e40: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
2e50: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
2e60: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
2e70: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
2e80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
2e90: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
2ea0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
2eb0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
2ec0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
2ed0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
2ee0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
2ef0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
2f00: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
2f10: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
2f20: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
2f30: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
2f40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f50: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
2f60: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
2f70: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f80: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
2f90: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
2fa0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
2fb0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
2fc0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
2fd0: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
2fe0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
2ff0: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3000: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3010: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3020: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3030: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3040: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3050: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3060: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3070: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3080: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3090: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
30a0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
30b0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
30c0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
30d0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
30e0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
30f0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3100: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3110: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3120: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3130: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3140: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3150: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3160: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3170: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3180: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3190: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
31a0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
31b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
31c0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
31d0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
31e0: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
31f0: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3200: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3210: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3220: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3230: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3240: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3250: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3260: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
3270: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
3280: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
3290: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
32a0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
32b0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
32c0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
32d0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
32e0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
32f0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3300: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3310: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3320: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3330: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3340: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3350: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3360: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
3370: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
3380: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
3390: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
33a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
33b0: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
33c0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
33d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
33e0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
33f0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
3400: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
3410: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
3420: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
3430: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
3440: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
3450: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3460: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3470: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3480: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3490: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
34a0: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
34b0: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
34c0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
34d0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
34e0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
34f0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
3500: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
3510: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
3520: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3530: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
3540: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
3550: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3560: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3570: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3580: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3590: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
35a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
35b0: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
35c0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
35d0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
35e0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
35f0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
3600: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3610: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3620: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
3630: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
3640: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
3650: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3660: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3670: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3680: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3690: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
36a0: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
36b0: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
36c0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
36d0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
36e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
36f0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
3700: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
3710: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3720: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
3730: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
3740: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
3750: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3760: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3770: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3780: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3790: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
37a0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
37b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
37c0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
37d0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
37e0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
37f0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
3800: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3810: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
3820: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
3830: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
3840: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
3850: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3860: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3870: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3880: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3890: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
38a0: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
38b0: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
38c0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
38d0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
38e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
38f0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3900: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3910: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3920: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3930: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3940: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3950: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3960: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3970: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3980: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3990: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
39a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
39b0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
39c0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
39d0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
39e0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
39f0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3a00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3a10: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3a20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3a30: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3a40: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3a50: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3a60: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3a70: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3a80: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3a90: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3aa0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3ab0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3ac0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3ad0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3ae0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3af0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3b00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3b10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3b20: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3b30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3b40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3b50: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3b60: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3b70: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3b80: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3b90: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ba0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3bb0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3bc0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3bd0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3be0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3bf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3c00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3c10: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3c20: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3c30: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3c40: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3c50: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3c60: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3c70: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3c80: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3c90: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3ca0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3cb0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3cc0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3cd0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3ce0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3cf0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3d00: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3d10: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
3d20: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
3d30: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
3d40: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
3d50: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3d60: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3d70: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3d80: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3d90: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3da0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3db0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3dc0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3dd0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3de0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3df0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
3e00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3e10: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
3e20: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3e30: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3e40: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
3e50: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
3e60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3e70: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
3e80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3e90: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
3ea0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3eb0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3ec0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3ed0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3ee0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3ef0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3f00: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3f10: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3f20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3f30: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3f40: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3f50: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
3f60: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
3f70: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
3f80: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3f90: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
3fa0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
3fb0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
3fc0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
3fd0: 2c 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 20 20                  
3ff0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4000: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4010: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4040: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4050: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4060: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4070: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
4080: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4090: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  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 20 20                  
40c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
40d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
40e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
40f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4110: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4120: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4130: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4140: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4150: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4160: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4170: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
4180: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4190: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
41a0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
41b0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
41c0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
41d0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
41e0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
41f0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4200: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4210: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4220: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4230: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4240: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4250: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4260: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
4270: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4280: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
4290: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
42a0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
42b0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
42c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
42d0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
42e0: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
42f0: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
4300: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4310: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4320: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4330: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4340: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4350: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4360: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4370: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4380: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4390: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
43a0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
43b0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
43c0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
43d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43e0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
43f0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4400: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4410: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4420: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4430: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4440: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4450: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4460: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4470: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4480: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
44a0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
44b0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
44c0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
44d0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
44e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
44f0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4500: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4510: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4520: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4540: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4550: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4560: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4570: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4580: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4590: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
45a0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
45b0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
45c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
45d0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
45e0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
45f0: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4600: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4610: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4620: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4630: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4640: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4650: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4660: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4670: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4680: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4690: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
46a0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
46b0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
46c0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
46d0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
46e0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
46f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4700: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4710: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
4720: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
4730: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4740: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4750: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4760: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4770: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4780: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4790: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
47a0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
47b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47c0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
47d0: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
47e0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
47f0: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4800: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4810: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4820: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4830: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4840: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4850: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4860: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4880: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4890: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
48a0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
48b0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
48c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
48d0: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
48e0: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
48f0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4900: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4910: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
4920: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
4930: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
4940: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4950: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4960: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4970: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4980: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
49a0: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
49b0: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
49c0: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
49d0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
49e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
49f0: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4a00: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4a10: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4a20: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4a30: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4a40: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4a50: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4a60: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4a70: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4a80: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4a90: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4aa0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4ab0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4ac0: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4ad0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4ae0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4af0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4b00: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4b10: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4b20: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4b30: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4b40: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4b50: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4b60: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4b70: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4b80: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4b90: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4ba0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4bb0: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4bc0: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4bd0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4be0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4bf0: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4c00: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4c10: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4c20: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4c30: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4c40: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4c50: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4c60: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4c70: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4c80: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4c90: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4ca0: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4cb0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4cc0: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4cd0: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4ce0: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
4cf0: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
4d00: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
4d10: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
4d20: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
4d30: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
4d40: 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65  ese [extended re
4d50: 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20  sult codes] are 
4d60: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
4d70: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20  led.** on a per 
4d80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4d90: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20  ion basis using 
4da0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4db0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
4dc0: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f  codes()] API.  O
4dd0: 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20  r, the extended 
4de0: 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  code for.** the 
4df0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f  most recent erro
4e00: 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  r can be obtaine
4e10: 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
4e20: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
4e30: 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  code()]..*/.#def
4e40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4e50: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
4e60: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e70: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
4e80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4e90: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
4ea0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4eb0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
4ec0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
4ed0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
4ee0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4ef0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
4f00: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
4f10: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
4f20: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f30: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
4f40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
4f50: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
4f60: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4f70: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
4f80: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
4f90: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
4fa0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
4fb0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4fc0: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
4fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4fe0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
4ff0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5000: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
5010: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5020: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
5030: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5040: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
5050: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5060: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
5070: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5080: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
5090: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
50b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50c0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
50d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
50f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5100: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
5110: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5120: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
5130: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5140: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
5150: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5160: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
5170: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5180: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
5190: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
51a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
51b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51c0: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
51d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
51f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5200: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20  E_IOERR_CLOSE   
5210: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5220: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38  E_IOERR | (16<<8
5230: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5240: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53  E_IOERR_DIR_CLOS
5250: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
5260: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38  E_IOERR | (17<<8
5270: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5280: 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20  E_IOERR_SHMOPEN 
5290: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38  E_IOERR | (18<<8
52b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
52c0: 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20  E_IOERR_SHMSIZE 
52d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38  E_IOERR | (19<<8
52f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5300: 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20  E_IOERR_SHMLOCK 
5310: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5320: 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38  E_IOERR | (20<<8
5330: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5340: 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20  E_IOERR_SHMMAP  
5350: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5360: 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38  E_IOERR | (21<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20  E_IOERR_SEEK    
5390: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38  E_IOERR | (22<<8
53b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
53c0: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e  E_IOERR_DELETE_N
53d0: 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54  OENT      (SQLIT
53e0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38  E_IOERR | (23<<8
53f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5400: 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20  E_IOERR_MMAP    
5410: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5420: 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38  E_IOERR | (24<<8
5430: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5440: 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50  E_IOERR_GETTEMPP
5450: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5460: 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38  E_IOERR | (25<<8
5470: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5480: 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48  E_IOERR_CONVPATH
5490: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
54a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38  E_IOERR | (26<<8
54b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
54c0: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43  E_LOCKED_SHAREDC
54d0: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54  ACHE      (SQLIT
54e0: 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c  E_LOCKED |  (1<<
54f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5500: 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59  TE_BUSY_RECOVERY
5510: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5520: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c  TE_BUSY   |  (1<
5530: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5540: 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f  ITE_BUSY_SNAPSHO
5550: 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  T           (SQL
5560: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32  ITE_BUSY   |  (2
5570: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5580: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5590: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
55a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
55b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
55c0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
55d0: 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28  ISDIR          (
55e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
55f0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5600: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5610: 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20  N_FULLPATH      
5620: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5630: 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  N | (3<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5650: 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20  PEN_CONVPATH    
5660: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5670: 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  PEN | (4<<8)).#d
5680: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
5690: 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20  RUPT_VTAB       
56a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52       (SQLITE_COR
56b0: 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  RUPT | (1<<8)).#
56c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
56d0: 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20  ADONLY_RECOVERY 
56e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
56f0: 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29  ADONLY | (1<<8))
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5710: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43  READONLY_CANTLOC
5720: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5730: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38  READONLY | (2<<8
5740: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5750: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42  E_READONLY_ROLLB
5760: 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  ACK       (SQLIT
5770: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c  E_READONLY | (3<
5780: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5790: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d  ITE_READONLY_DBM
57a0: 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c  OVED        (SQL
57b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
57c0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
57d0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
57e0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
57f0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5800: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5810: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5820: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5830: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5840: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5850: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5860: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5870: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5880: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5890: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
58a0: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
58b0: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
58c0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
58d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
58e0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
58f0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5900: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5910: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5920: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5930: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
5940: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5950: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5960: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5970: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
5980: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5990: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
59a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59b0: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
59c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
59d0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
59e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
59f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
5a00: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
5a20: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a30: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a40: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a60: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
5a70: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5a80: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
5a90: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5aa0: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
5ab0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5ac0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
5ad0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
5ae0: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
5af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5b00: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
5b10: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
5b20: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
5b30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
5b40: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
5b50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
5b60: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
5b70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
5b80: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
5b90: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
5ba0: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a  TH | (1<<8))../*
5bb0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
5bc0: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
5bd0: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
5be0: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
5bf0: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
5c00: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
5c10: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
5c20: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5c30: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
5c40: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
5c50: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
5c60: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5c70: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
5c80: 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  hod..*/.#define 
5c90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5ca0: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30  ONLY         0x0
5cb0: 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66  0000001  /* Ok f
5cc0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5cd0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5ce0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5cf0: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30  WRITE        0x0
5d00: 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66  0000002  /* Ok f
5d10: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5d20: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5d30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
5d40: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30  TE           0x0
5d50: 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66  0000004  /* Ok f
5d60: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5d70: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5d80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
5d90: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30  TEONCLOSE    0x0
5da0: 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20  0000008  /* VFS 
5db0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5dc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
5dd0: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30  USIVE        0x0
5de0: 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20  0000010  /* VFS 
5df0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5e00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f  SQLITE_OPEN_AUTO
5e10: 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30  PROXY        0x0
5e20: 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20  0000020  /* VFS 
5e30: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5e40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
5e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5e60: 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66  0000040  /* Ok f
5e70: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5e80: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5e90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f  SQLITE_OPEN_MEMO
5ea0: 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30  RY           0x0
5eb0: 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66  0000080  /* Ok f
5ec0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5ed0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5ee0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5ef0: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5f00: 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20  0000100  /* VFS 
5f10: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5f20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
5f30: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5f40: 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20  0000200  /* VFS 
5f50: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5f60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
5f70: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30  SIENT_DB     0x0
5f80: 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20  0000400  /* VFS 
5f90: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5fa0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5fb0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
5fc0: 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20  0000800  /* VFS 
5fd0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5fe0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
5ff0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
6000: 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20  0001000  /* VFS 
6010: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6020: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
6030: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30  OURNAL       0x0
6040: 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20  0002000  /* VFS 
6050: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6060: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
6070: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30  ER_JOURNAL   0x0
6080: 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20  0004000  /* VFS 
6090: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
60a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
60b0: 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30  TEX          0x0
60c0: 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0008000  /* Ok f
60d0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
60e0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
60f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
6100: 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30  MUTEX        0x0
6110: 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0010000  /* Ok f
6120: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6130: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6140: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
6150: 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30  EDCACHE      0x0
6160: 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0020000  /* Ok f
6170: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6180: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6190: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
61a0: 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30  ATECACHE     0x0
61b0: 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0040000  /* Ok f
61c0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
61d0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
61e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20  SQLITE_OPEN_WAL 
61f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6200: 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20  0080000  /* VFS 
6210: 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65  only */../* Rese
6220: 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20  rved:           
6230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6240: 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a  00F00000 */../*.
6250: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76  ** CAPI3REF: Dev
6260: 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74  ice Characterist
6270: 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  ics.**.** The xD
6280: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6290: 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  tics method of t
62a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
62b0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
62c0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
62d0: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
62e0: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a  vector of these.
62f0: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
6300: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
6310: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
6320: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
6330: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
6340: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
6350: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
6360: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
6370: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
6380: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6390: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
63a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
63b0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
63c0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
63d0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
63e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
63f0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6400: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6410: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6420: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6430: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6440: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6450: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6460: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6470: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6480: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6490: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
64a0: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
64b0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
64c0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
64d0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
64e0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
64f0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6500: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6510: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6520: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6530: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6540: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6550: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6560: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6570: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6580: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6590: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
65a0: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
65b0: 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c  rite().  The SQL
65c0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
65d0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72  AFE_OVERWRITE pr
65e0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
65f0: 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f  t.** after reboo
6600: 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72  t following a cr
6610: 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73  ash or power los
6620: 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65  s, the only byte
6630: 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74  s in a.** file t
6640: 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e  hat were written
6650: 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74   at the applicat
6660: 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20  ion level might 
6670: 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  have changed.** 
6680: 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e  and that adjacen
6690: 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79  t bytes, even by
66a0: 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73  tes within the s
66b0: 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a  ame sector are.*
66c0: 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  * guaranteed to 
66d0: 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  be unchanged.  T
66e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
66f0: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
6700: 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e  _OPEN.** flag in
6710: 64 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69  dicate that a fi
6720: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c  le cannot be del
6730: 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20  eted when open. 
6740: 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49   The.** SQLITE_I
6750: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66  OCAP_IMMUTABLE f
6760: 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68  lag indicates th
6770: 61 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f  at the file is o
6780: 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  n.** read-only m
6790: 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20  edia and cannot 
67a0: 62 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20  be changed even 
67b0: 62 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74  by processes wit
67c0: 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72  h.** elevated pr
67d0: 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65  ivileges..*/.#de
67e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
67f0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
6800: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6810: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
6820: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6830: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
6840: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
6850: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6860: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
6870: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6880: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
6890: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
68a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
68b0: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
68c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
68d0: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
68e0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
68f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6900: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
6910: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6920: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
6930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6940: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
6950: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
6960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6970: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
6980: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6990: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
69a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
69b0: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
69c0: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
69d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
69e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
69f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6a00: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6a10: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6a20: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
6a30: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
6a40: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6a50: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6a60: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
6a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a80: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6a90: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
6aa0: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
6ab0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6ac0: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  UTABLE          
6ad0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a      0x00002000..
6ae0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6af0: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
6b00: 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  els.**.** SQLite
6b10: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
6b20: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
6b30: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
6b40: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
6b50: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
6b60: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
6b70: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
6b80: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
6b90: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6ba0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
6bb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6bc0: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6be0: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
6bf0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
6c00: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
6c10: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
6c20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6c30: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
6c40: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6c50: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
6c60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6c70: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
6c80: 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a   Type Flags.**.*
6c90: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  * When SQLite in
6ca0: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
6cb0: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
6cc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6cd0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
6ce0: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
6cf0: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  ion of.** these 
6d00: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
6d10: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
6d20: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ument..**.** Whe
6d30: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  n the SQLITE_SYN
6d40: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20  C_DATAONLY flag 
6d50: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e  is used, it mean
6d60: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79  s that the.** sy
6d70: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c  nc operation onl
6d80: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68  y needs to flush
6d90: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74   data to mass st
6da0: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a  orage.  Inode.**
6db0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65   information nee
6dc0: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64  d not be flushed
6dd0: 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  . If the lower f
6de0: 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20  our bits of the 
6df0: 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51  flag.** equal SQ
6e00: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6e10: 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20  , that means to 
6e20: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
6e30: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a  () semantics..**
6e40: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6e50: 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51  ur bits equal SQ
6e60: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
6e70: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f  that means.** to
6e80: 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74   use Mac OS X st
6e90: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73  yle fullsync ins
6ea0: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
6eb0: 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f  .**.** Do not co
6ec0: 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45  nfuse the SQLITE
6ed0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6ee0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6ef0: 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20  L flags.** with 
6f00: 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  the [PRAGMA sync
6f10: 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20  hronous]=NORMAL 
6f20: 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  and [PRAGMA sync
6f30: 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a  hronous]=FULL.**
6f40: 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20   settings.  The 
6f50: 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61  [synchronous pra
6f60: 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20  gma] determines 
6f70: 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68  when calls to th
6f80: 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d  e.** xSync VFS m
6f90: 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20  ethod occur and 
6fa0: 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c  applies uniforml
6fb0: 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61  y across all pla
6fc0: 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53  tforms..** The S
6fd0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6fe0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
6ff0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74  C_FULL flags det
7000: 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e  ermine how.** en
7010: 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72  ergetic or rigor
7020: 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20  ous or forceful 
7030: 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69  the sync operati
7040: 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f  ons are and.** o
7050: 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65  nly make a diffe
7060: 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58  rence on Mac OSX
7070: 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74   for the default
7080: 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a   SQLite code..**
7090: 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46   (Third-party VF
70a0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
70b0: 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b  s might also mak
70c0: 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
70d0: 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
70e0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
70f0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7100: 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20  FULL, but among 
7110: 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67  the.** operating
7120: 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c   systems nativel
7130: 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  y supported by S
7140: 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20  QLite, only Mac 
7150: 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f  OSX.** cares abo
7160: 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63  ut the differenc
7170: 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e.).*/.#define S
7180: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7190: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
71a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71b0: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
71c0: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
71d0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
71e0: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
71f0: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
7200: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
7210: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
7220: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  dle.**.** An [sq
7230: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7240: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
7250: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
7260: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  e .** [sqlite3_v
7270: 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63  fs | OS interfac
7280: 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76  e layer].  Indiv
7290: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
72a0: 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ce.** implementa
72b0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
72c0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
72d0: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
72e0: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
72f0: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
7300: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
7310: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
7320: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
7330: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
7340: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7350: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
7360: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
7370: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
7380: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
7390: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
73a0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
73b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
73c0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
73d0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
73e0: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
73f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7400: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
7410: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
7420: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
7430: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7440: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
7450: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
7460: 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ods Object.**.**
7470: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
7480: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7490: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
74a0: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
74b0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
74c0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
74d0: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
74e0: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
74f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7500: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
7510: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
7520: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
7530: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
7540: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
7550: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
7560: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
7570: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
7580: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
7590: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
75a0: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
75b0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
75c0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
75d0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
75e0: 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74  n] method sets t
75f0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
7600: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7610: 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55   .** to a non-NU
7620: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
7630: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f   the sqlite3_io_
7640: 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d  methods.xClose m
7650: 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20  ethod.** may be 
7660: 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20  invoked even if 
7670: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7680: 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64  .xOpen] reported
7690: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
76a0: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
76b0: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
76c0: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
76d0: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
76e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
76f0: 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74  pen].** is for t
7700: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7710: 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68  xOpen] to set th
7720: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7730: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a  Methods element.
7740: 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ** to NULL..**.*
7750: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
7760: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
7770: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
7780: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
7790: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
77a0: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
77b0: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
77c0: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
77d0: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
77e0: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
77f0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
7800: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
7810: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7820: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
7830: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
7840: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
7850: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
7860: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
7870: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
7880: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
7890: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
78a0: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
78b0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
78c0: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
78d0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
78e0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
78f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7900: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
7910: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7920: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
7930: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7940: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
7950: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7960: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
7970: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
7980: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
7990: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
79a0: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
79b0: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
79c0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
79d0: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
79e0: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
79f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
7a00: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
7a10: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
7a20: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
7a30: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
7a40: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
7a50: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
7a60: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
7a70: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
7a80: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
7a90: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
7aa0: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
7ab0: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
7ac0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7ad0: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
7ae0: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
7af0: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
7b00: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
7b10: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
7b20: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
7b30: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
7b40: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7b50: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
7b60: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
7b70: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
7b80: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
7b90: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
7ba0: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
7bb0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
7bc0: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
7bd0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
7be0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
7bf0: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
7c00: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
7c10: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
7c20: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
7c30: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
7c40: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
7c50: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
7c60: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
7c70: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
7c80: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
7c90: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
7ca0: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
7cb0: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
7cc0: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
7cd0: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
7ce0: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
7cf0: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
7d00: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
7d10: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
7d20: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
7d30: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
7d40: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
7d50: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
7d60: 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63  se..** A [file c
7d70: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c  ontrol opcodes |
7d80: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
7d90: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
7da0: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
7db0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
7dc0: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
7dd0: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
7de0: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
7df0: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
7e00: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
7e10: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
7e20: 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  .  VFS implement
7e30: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a  ations should.**
7e40: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
7e50: 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69  NOTFOUND] for fi
7e60: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
7e70: 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  es that they do 
7e80: 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65  not.** recognize
7e90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
7ea0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
7eb0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
7ec0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
7ed0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
7ee0: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
7ef0: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
7f00: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
7f10: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
7f20: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
7f30: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
7f40: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
7f50: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
7f60: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
7f70: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
7f80: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
7f90: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
7fa0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
7fb0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
7fc0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
7fd0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
7fe0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7ff0: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
8000: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8010: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
8020: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8030: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
8040: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8050: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
8060: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8070: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
8080: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8090: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
80a0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
80b0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
80c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
80d0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
80e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
80f0: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
8100: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8110: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
8120: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8130: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
8140: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
8150: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8160: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
8170: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
8180: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
8190: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
81a0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
81b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
81c0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
81d0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
81e0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
81f0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
8200: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
8210: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
8220: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
8230: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
8240: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
8250: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8260: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
8270: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
8280: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
8290: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
82a0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
82b0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
82c0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
82d0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
82e0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
82f0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
8300: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
8310: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8320: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
8330: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
8340: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
8350: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
8360: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
8370: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
8380: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
8390: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
83a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
83b0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
83c0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
83d0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
83e0: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
83f0: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
8400: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
8410: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
8420: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
8430: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
8440: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
8450: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
8460: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
8470: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
8480: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
8490: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
84a0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
84b0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
84c0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
84d0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
84e0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
84f0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
8500: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
8510: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
8520: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
8530: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
8540: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
8550: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8560: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8570: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
8580: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
8590: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
85a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
85b0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
85c0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
85d0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
85e0: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
85f0: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
8600: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
8610: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
8620: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
8630: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8640: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
8650: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
8660: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8670: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
8680: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8690: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
86a0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
86b0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
86c0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
86d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
86e0: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
86f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
8700: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
8710: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
8720: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8730: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
8740: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8750: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8760: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8770: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8780: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
8790: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
87a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
87b0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
87c0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
87d0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
87e0: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
87f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8800: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
8810: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
8820: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
8830: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8840: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
8850: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8860: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
8870: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8880: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8890: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
88a0: 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29  .  int (*xFetch)
88b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88c0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
88d0: 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76  fst, int iAmt, v
88e0: 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74  oid **pp);.  int
88f0: 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c   (*xUnfetch)(sql
8900: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8910: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8920: 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20   void *p);.  /* 
8930: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8940: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8950: 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 3 */.  /* Ad
8960: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
8970: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8980: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
8990: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
89a0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
89b0: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
89c0: 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  codes.** KEYWORD
89d0: 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  S: {file control
89e0: 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20   opcodes} {file 
89f0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a  control opcode}.
8a00: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
8a10: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
8a20: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
8a30: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
8a40: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
8a50: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
8a60: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
8a70: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
8a80: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8a90: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
8aa0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
8ab0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8ac0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8ad0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
8ae0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
8af0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
8b00: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
8b10: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
8b20: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
8b30: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
8b40: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
8b50: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
8b60: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
8b70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8b80: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
8b90: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
8ba0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8bb0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
8bc0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
8bd0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
8be0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
8bf0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
8c00: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
8c10: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79  testing and only
8c20: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
8c30: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
8c40: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65  TE_TEST.** is de
8c50: 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a  fined..** <ul>.*
8c60: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8c70: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8c80: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8c90: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8ca0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8cb0: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8cc0: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8cd0: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8ce0: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8cf0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8d00: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8d10: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8d20: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8d30: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8d40: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8d50: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8d60: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8d70: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8d80: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8d90: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8da0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8db0: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8dc0: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8dd0: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8de0: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8df0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8e00: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8e10: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8e20: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
8e30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8e40: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8e50: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8e60: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
8e70: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
8e80: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
8e90: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8ea0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
8eb0: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
8ec0: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
8ed0: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
8ee0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
8ef0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
8f00: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
8f10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
8f20: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
8f30: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
8f40: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
8f50: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
8f60: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
8f70: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
8f80: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
8f90: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
8fa0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
8fb0: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
8fc0: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
8fd0: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
8fe0: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
8ff0: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9000: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
9010: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9020: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
9030: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9040: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
9050: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9060: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9070: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9080: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9090: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
90a0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
90b0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
90c0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
90d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
90e0: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
90f0: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
9100: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
9110: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
9120: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9130: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
9140: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
9150: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
9160: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9170: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
9180: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
9190: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
91a0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
91b0: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
91c0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
91d0: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
91e0: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
91f0: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
9200: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
9210: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
9220: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
9230: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
9240: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
9250: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
9260: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
9270: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
9280: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9290: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
92a0: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
92b0: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
92c0: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
92d0: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
92e0: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
92f0: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
9300: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
9310: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
9320: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
9330: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
9340: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
9350: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
9360: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
9370: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
9380: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
9390: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
93a0: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
93b0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
93c0: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
93d0: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
93e0: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
93f0: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
9400: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
9410: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
9420: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
9430: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
9440: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
9450: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9460: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9470: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9480: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
9490: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
94a0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
94b0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
94c0: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
94d0: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
94e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
94f0: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
9500: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9510: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
9520: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
9530: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9540: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
9550: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
9560: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
9570: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
9580: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
9590: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
95a0: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
95b0: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
95c0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
95d0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
95e0: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
95f0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
9600: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
9610: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
9620: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
9630: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9640: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9650: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9660: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
9670: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
9680: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9690: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
96a0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
96b0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
96c0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
96d0: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
96e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
96f0: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9700: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9710: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9720: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
9730: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
9740: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
9750: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
9760: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9770: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
9780: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9790: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
97a0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
97b0: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
97c0: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
97d0: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
97e0: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
97f0: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9800: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9810: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9820: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
9830: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
9840: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
9850: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
9860: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9870: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
9880: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9890: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
98a0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
98b0: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
98c0: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
98d0: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
98e0: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
98f0: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9900: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9910: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9920: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9930: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9940: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9950: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9960: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9970: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9980: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9990: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
99a0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
99b0: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
99c0: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
99d0: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
99e0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
99f0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9a00: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9a10: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9a20: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9a30: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9a40: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9a50: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9a60: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9a70: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9a80: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9a90: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9aa0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9ab0: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9ac0: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9ad0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9ae0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9af0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9b00: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9b10: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9b20: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9b30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9b40: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9b50: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9b60: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9b70: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9b80: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9b90: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9ba0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9bb0: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9bc0: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9bd0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9be0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9bf0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9c00: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9c10: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9c20: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9c30: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9c40: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9c50: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9c60: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9c70: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
9c80: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9c90: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9ca0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9cb0: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9cc0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9cd0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9ce0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9cf0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9d00: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9d10: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9d20: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9d30: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9d40: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9d50: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9d60: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9d70: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9d80: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9d90: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9da0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9db0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9dc0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9dd0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9de0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9df0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9e00: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9e10: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9e20: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9e30: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9e40: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9e50: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9e60: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9e70: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9e80: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9e90: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9ea0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
9eb0: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
9ec0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9ed0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9ee0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
9ef0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9f00: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
9f10: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9f20: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9f30: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9f40: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
9f50: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
9f60: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
9f70: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
9f80: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
9f90: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
9fa0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
9fb0: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
9fc0: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
9fd0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
9fe0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
9ff0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a000: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a010: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a020: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a030: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a040: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a050: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a060: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a070: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a080: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a090: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a0a0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a0b0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a0c0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a0d0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a0e0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a0f0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a100: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a110: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a120: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a130: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a140: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a150: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a160: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a170: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a180: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a190: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a1a0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a1b0: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a1c0: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a1d0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a1e0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a1f0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a200: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a210: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a220: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a230: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a240: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a250: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a260: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a270: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a280: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a290: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a2a0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a2b0: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a2c0: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a2d0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a2e0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a2f0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a300: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a310: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a320: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a330: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a340: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a350: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a360: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a370: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a380: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a390: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a3a0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a3b0: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a3c0: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a3d0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a3e0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a3f0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a400: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a410: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a420: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a430: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a440: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a450: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a460: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a470: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a480: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a490: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a4a0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a4b0: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a4c0: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a4d0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a4e0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a4f0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a500: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a510: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a520: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a530: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a540: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a550: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a560: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a570: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a580: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a590: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a5a0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
a5b0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
a5c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
a5d0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a5e0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a5f0: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a600: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a610: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a620: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a630: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a640: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a650: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a660: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a670: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a680: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a690: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a6a0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a6b0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a6c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a6d0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a6e0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a6f0: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a700: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a710: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a720: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a730: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a740: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a750: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a760: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a770: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a780: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a790: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a7a0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a7b0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a7c0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a7d0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a7e0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a7f0: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a800: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a810: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a820: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a830: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a840: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a850: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a860: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a870: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
a880: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
a890: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
a8a0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a8b0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
a8c0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
a8d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
a8e0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
a8f0: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
a900: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
a910: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
a920: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
a930: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
a940: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
a950: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
a960: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
a970: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a980: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a990: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
a9a0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
a9b0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
a9c0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
a9d0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
a9e0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
a9f0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
aa00: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
aa10: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
aa20: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
aa30: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
aa40: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
aa50: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
aa60: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aa70: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
aa80: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
aa90: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
aaa0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
aab0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
aac0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
aad0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
aae0: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
aaf0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
ab00: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ab10: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
ab20: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
ab30: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
ab40: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
ab50: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
ab60: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
ab70: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
ab80: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
ab90: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
aba0: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
abb0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
abc0: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
abd0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
abe0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
abf0: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
ac00: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
ac10: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
ac20: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
ac30: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
ac40: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
ac50: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
ac60: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
ac70: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
ac80: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
ac90: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
aca0: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
acb0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
acc0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
acd0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
ace0: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
acf0: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
ad00: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
ad10: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
ad20: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
ad30: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
ad40: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
ad50: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
ad60: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
ad70: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
ad80: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
ad90: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
ada0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
adb0: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
adc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
add0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
ade0: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
adf0: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
ae00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
ae10: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
ae20: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
ae30: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
ae40: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
ae50: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
ae60: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
ae70: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
ae80: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
ae90: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
aea0: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
aeb0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
aec0: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
aed0: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
aee0: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
aef0: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
af00: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
af10: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
af20: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
af30: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
af40: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
af50: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
af60: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
af70: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
af80: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
af90: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
afa0: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
afb0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
afc0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
afd0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
afe0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
aff0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b000: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
b010: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
b020: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
b030: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
b040: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
b050: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
b060: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b070: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
b080: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
b090: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
b0a0: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
b0b0: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
b0c0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
b0d0: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
b0e0: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
b0f0: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
b100: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
b110: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
b120: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
b130: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
b140: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
b150: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
b160: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
b170: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
b180: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
b190: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
b1a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
b1b0: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
b1c0: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
b1d0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
b1e0: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
b1f0: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
b200: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
b210: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b220: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
b230: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
b240: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
b250: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
b260: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
b270: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
b280: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
b290: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
b2a0: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
b2b0: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
b2c0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
b2d0: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
b2e0: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
b2f0: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
b300: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b310: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
b320: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
b330: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
b340: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
b350: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
b360: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
b370: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
b380: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
b390: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
b3a0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b3b0: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
b3c0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b3d0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
b3e0: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ED]].** The [SQL
b3f0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
b400: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  VED] file contro
b410: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
b420: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a   argument as a.*
b430: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
b440: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77  integer and it w
b450: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20  rites a boolean 
b460: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
b470: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  r depending.** o
b480: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
b490: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65   the file has be
b4a0: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65  en renamed, move
b4b0: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69  d, or deleted si
b4c0: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69  nce it.** was fi
b4d0: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  rst opened..**.*
b4e0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b4f0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
b500: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
b510: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b520: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_SET_HANDLE] o
b530: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
b540: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
b550: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
b560: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
b570: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73  trol method to s
b580: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e  wap the file han
b590: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65  dle with the one
b5a0: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
b5b0: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  y the pArg argum
b5c0: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62  ent.  This capab
b5d0: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75  ility is used du
b5e0: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20  ring testing.** 
b5f0: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
b600: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
b610: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20  hen SQLITE_TEST 
b620: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
b630: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </ul>.*/.#defi
b640: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b650: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
b660: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
b670: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47  e SQLITE_FCNTL_G
b680: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
b690: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
b6a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
b6b0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
b6c0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
b6d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
b6e0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
b6f0: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
b700: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
b710: 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  _HINT           
b720: 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
b730: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
b740: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
b750: 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
b760: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
b770: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
b780: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
b790: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
b7a0: 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20  ITTED           
b7b0: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
b7c0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
b7d0: 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20  _RETRY          
b7e0: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
b7f0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
b800: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30  AL            10
b810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b820: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20  FCNTL_OVERWRITE 
b830: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a               11.
b840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b850: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20  CNTL_VFSNAME    
b860: 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23              12.#
b870: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b880: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
b890: 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64  ERWRITE    13.#d
b8a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b8b0: 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TL_PRAGMA       
b8c0: 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65            14.#de
b8d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b8e0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20  L_BUSYHANDLER   
b8f0: 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66           15.#def
b900: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b910: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20  _TEMPFILENAME   
b920: 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69          16.#defi
b930: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b940: 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20  MMAP_SIZE       
b950: 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e         18.#defin
b960: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
b970: 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20  RACE            
b980: 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65        19.#define
b990: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41   SQLITE_FCNTL_HA
b9a0: 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20  S_MOVED         
b9b0: 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20       20.#define 
b9c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
b9d0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
b9e0: 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53      21.#define S
b9f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
ba00: 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20  IT_PHASETWO     
ba10: 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51     22.#define SQ
ba20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
ba30: 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20  _SET_HANDLE     
ba40: 20 20 32 33 0a 0a 2f 2a 20 64 65 70 72 65 63 61    23../* depreca
ba50: 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65  ted names */.#de
ba60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
ba70: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
ba80: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
ba90: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
baa0: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
bab0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
bac0: 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46  LE      SQLITE_F
bad0: 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_SET_LOCKPRO
bae0: 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53  XYFILE.#define S
baf0: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
bb00: 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c               SQL
bb10: 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45  ITE_FCNTL_LAST_E
bb20: 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  RRNO.../*.** CAP
bb30: 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e  I3REF: Mutex Han
bb40: 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75  dle.**.** The mu
bb50: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69  tex module withi
bb60: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73  n SQLite defines
bb70: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
bb80: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73   to be an.** abs
bb90: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61  tract type for a
bba0: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20   mutex object.  
bbb0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
bbc0: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61  never looks.** a
bbd0: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  t the internal r
bbe0: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66  epresentation of
bbf0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
bc00: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a  ex].  It only.**
bc10: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e   deals with poin
bc20: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  ters to the [sql
bc30: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65  ite3_mutex] obje
bc40: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65  ct..**.** Mutexe
bc50: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
bc60: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
bc70: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  ex_alloc()]..*/.
bc80: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
bc90: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c  qlite3_mutex sql
bca0: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a  ite3_mutex;../*.
bcb0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
bcc0: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
bcd0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
bce0: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
bcf0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
bd00: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
bd10: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
bd20: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
bd30: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
bd40: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
bd50: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
bd60: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
bd70: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
bd80: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
bd90: 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65  ile system".  Se
bda0: 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20  e.** the [VFS | 
bdb0: 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  VFS documentatio
bdc0: 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69  n] for further i
bdd0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
bde0: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
bdf0: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
be00: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
be10: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
be20: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
be30: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
be40: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
be50: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
be60: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
be70: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
be80: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
be90: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
bea0: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
beb0: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
bec0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
bed0: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
bee0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
bef0: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
bf00: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
bf10: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
bf20: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
bf30: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
bf40: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
bf50: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
bf60: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
bf70: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
bf80: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
bf90: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
bfa0: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
bfb0: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
bfc0: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
bfd0: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
bfe0: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
bff0: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
c000: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
c010: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
c020: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
c030: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
c040: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
c050: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
c060: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
c070: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
c080: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
c090: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
c0a0: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
c0b0: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
c0c0: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
c0d0: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
c0e0: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
c0f0: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
c100: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
c110: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
c120: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
c130: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
c140: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
c150: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
c160: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
c170: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
c180: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
c190: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
c1a0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
c1b0: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
c1c0: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
c1d0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
c1e0: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
c1f0: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
c200: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
c210: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
c220: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
c230: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
c240: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
c250: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
c260: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
c270: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
c280: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
c290: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
c2a0: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
c2b0: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
c2c0: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
c2d0: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
c2e0: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
c2f0: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  modules..**.** [
c300: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
c310: 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  en]].** ^SQLite 
c320: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
c330: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
c340: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
c350: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20  .** is either a 
c360: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
c370: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a  string obtained.
c380: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74  ** from xFullPat
c390: 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20  hname() with an 
c3a0: 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20  optional suffix 
c3b0: 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20  added..** ^If a 
c3c0: 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20  suffix is added 
c3d0: 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  to the zFilename
c3e0: 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77   parameter, it w
c3f0: 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f  ill.** consist o
c400: 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63  f a single "-" c
c410: 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65  haracter followe
c420: 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61  d by no more tha
c430: 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d  n.** 11 alphanum
c440: 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20  eric and/or "-" 
c450: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e  characters..** ^
c460: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
c470: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
c480: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
c490: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
c4a0: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
c4b0: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
c4c0: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66  lled. Because of
c4d0: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
c4e0: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntence,.** the [
c4f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
c500: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
c510: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
c520: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
c530: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
c540: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
c550: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
c560: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
c570: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
c580: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  to xOpen is a NU
c590: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
c5a0: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
c5b0: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d  vent its own tem
c5c0: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
c5d0: 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e  the file.  ^When
c5e0: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69  ever the .** xFi
c5f0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
c600: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c   is NULL it will
c610: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73   also be the cas
c620: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c  e that the.** fl
c630: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69  ags parameter wi
c640: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ll include [SQLI
c650: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
c660: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  CLOSE]..**.** Th
c670: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
c680: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c   to xOpen() incl
c690: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65  udes all bits se
c6a0: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67  t in.** the flag
c6b0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  s argument to [s
c6c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
c6d0: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74  ].  Or if [sqlit
c6e0: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72  e3_open()].** or
c6f0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
c700: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65  ()] is used, the
c710: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73  n flags includes
c720: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51   at least.** [SQ
c730: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
c740: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
c750: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a  PEN_CREATE]. .**
c760: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e   If xOpen() open
c770: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e  s a file read-on
c780: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20  ly then it sets 
c790: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a  *pOutFlags to.**
c7a0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
c7b0: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e  _OPEN_READONLY].
c7c0: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20    Other bits in 
c7d0: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62  *pOutFlags may b
c7e0: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53  e set..**.** ^(S
c7f0: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20  QLite will also 
c800: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
c810: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
c820: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
c830: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67   call, depending
c840: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62   on the object b
c850: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a  eing opened:.**.
c860: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
c870: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
c880: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
c890: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
c8a0: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
c8b0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c8c0: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
c8d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c8e0: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
c8f0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c900: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
c910: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c920: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
c930: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
c940: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
c950: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
c960: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c970: 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  WAL].** </ul>)^.
c980: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
c990: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
c9a0: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
c9b0: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
c9c0: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  to.** change the
c9d0: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
c9e0: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
c9f0: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
ca00: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
ca10: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
ca20: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
ca30: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
ca40: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
ca50: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
ca60: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
ca70: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
ca80: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
ca90: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
caa0: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
cab0: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
cac0: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
cad0: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52  n.** SQLITE_IOER
cae0: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  R.  Or the imple
caf0: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
cb00: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61  recognize that a
cb10: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
cb20: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20  e will be doing 
cb30: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63  page-aligned sec
cb40: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72  tor reads and wr
cb50: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d  ites in a random
cb60: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65  .** order and se
cb70: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62  t up its I/O sub
cb80: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67  system according
cb90: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ly..**.** SQLite
cba0: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
cbb0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
cbc0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
cbd0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a  e xOpen method:.
cbe0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
cbf0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
cc00: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
cc10: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
cc20: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
cc30: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
cc40: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
cc50: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
cc60: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
cc70: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
cc80: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
cc90: 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20  s closed.  ^The 
cca0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
ccb0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77  ETEONCLOSE].** w
ccc0: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54  ill be set for T
ccd0: 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e  EMP databases an
cce0: 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73  d their journals
ccf0: 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64  , transient.** d
cd00: 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75  atabases, and su
cd10: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
cd20: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
cd30: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
cd40: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  ag is always use
cd50: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e  d in conjunction
cd60: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
cd70: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
cd80: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72  ] flag, which ar
cd90: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a  e both directly.
cda0: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20  ** analogous to 
cdb0: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f  the O_EXCL and O
cdc0: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20  _CREAT flags of 
cdd0: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29  the POSIX open()
cde0: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51  .** API.  The SQ
cdf0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
ce00: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70  IVE flag, when p
ce10: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a  aired with the .
ce20: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ** SQLITE_OPEN_C
ce30: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74  REATE, is used t
ce40: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
ce50: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61  file should alwa
ce60: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64  ys.** be created
ce70: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73  , and that it is
ce80: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20   an error if it 
ce90: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a  already exists..
cea0: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c  ** It is <i>not<
ceb0: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69  /i> used to indi
cec0: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68  cate the file sh
ced0: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a  ould be opened .
cee0: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65  ** for exclusive
cef0: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e   access..**.** ^
cf00: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
cf10: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
cf20: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  y are allocated 
cf30: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20  by SQLite.** to 
cf40: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
cf50: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
cf60: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
cf70: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
cf80: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68  nt to xOpen.  Th
cf90: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
cfa0: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
cfb0: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
cfc0: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
cfd0: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
cfe0: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74  t in.  Note that
cff0: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65  .** the xOpen me
d000: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68  thod must set th
d010: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
d020: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65  Methods to eithe
d030: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71  r.** a valid [sq
d040: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
d050: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e  ] object or to N
d060: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74  ULL.  xOpen must
d070: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e   do.** this even
d080: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
d090: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65  ls.  SQLite expe
d0a0: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c  cts that the sql
d0b0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
d0c0: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69  ds.** element wi
d0d0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65  ll be valid afte
d0e0: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20  r xOpen returns 
d0f0: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
d100: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20  e success.** or 
d110: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78  failure of the x
d120: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  Open call..**.**
d130: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
d140: 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65  Access]].** ^The
d150: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
d160: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
d170: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
d180: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
d190: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
d1a0: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
d1b0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
d1c0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
d1d0: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
d1e0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
d1f0: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
d200: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
d210: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
d220: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
d230: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
d240: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
d250: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
d260: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
d270: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
d280: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
d290: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
d2a0: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
d2b0: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
d2c0: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
d2d0: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20  ame.  The exact 
d2e0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
d2f0: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
d300: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61  also passed as a
d310: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f   parameter to bo
d320: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20  th  methods. If 
d330: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
d340: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
d350: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
d360: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
d370: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
d380: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
d390: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
d3a0: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
d3b0: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
d3c0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
d3d0: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
d3e0: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
d3f0: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
d400: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
d410: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
d420: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
d430: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
d440: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65  (), xCurrentTime
d450: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
d460: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69  TimeInt64().** i
d470: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f  nterfaces are no
d480: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
d490: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
d4a0: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
d4b0: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
d4c0: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
d4d0: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
d4e0: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
d4f0: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
d500: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
d510: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
d520: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
d530: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
d540: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
d550: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
d560: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
d570: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
d580: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
d590: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
d5a0: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
d5b0: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
d5c0: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
d5d0: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
d5e0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
d5f0: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
d600: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e  n.  ^The xCurren
d610: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
d620: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
d630: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
d640: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
d650: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a  te and time as.*
d660: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  * a floating poi
d670: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68  nt value..** ^Th
d680: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
d690: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74  t64() method ret
d6a0: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65  urns, as an inte
d6b0: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a  ger, the Julian.
d6c0: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75  ** Day Number mu
d6d0: 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30  ltiplied by 8640
d6e0: 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72  0000 (the number
d6f0: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
d700: 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75   in .** a 24-hou
d710: 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51  r day).  .** ^SQ
d720: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
d730: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
d740: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20  t64() method to 
d750: 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a  get the current.
d760: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  ** date and time
d770: 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20   if that method 
d780: 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66  is available (if
d790: 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f   iVersion is 2 o
d7a0: 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e  r .** greater an
d7b0: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  d the function p
d7c0: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
d7d0: 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c  LL) and will fal
d7e0: 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75  l back.** to xCu
d7f0: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78  rrentTime() if x
d800: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
d810: 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  () is unavailabl
d820: 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53  e..**.** ^The xS
d830: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
d840: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xGetSystemCall()
d850: 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65  , and xNestSyste
d860: 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  mCall() interfac
d870: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73  es.** are not us
d880: 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65  ed by the SQLite
d890: 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70   core.  These op
d8a0: 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65  tional interface
d8b0: 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a  s are provided.*
d8c0: 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20  * by some VFSes 
d8d0: 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65  to facilitate te
d8e0: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53  sting of the VFS
d8f0: 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69   code. By overri
d900: 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20  ding .** system 
d910: 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74  calls with funct
d920: 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63  ions under its c
d930: 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70  ontrol, a test p
d940: 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69  rogram can.** si
d950: 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e  mulate faults an
d960: 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f  d error conditio
d970: 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74  ns that would ot
d980: 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69  herwise be diffi
d990: 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73  cult.** or impos
d9a0: 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e  sible to induce.
d9b0: 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73    The set of sys
d9c0: 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63  tem calls that c
d9d0: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
d9e0: 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20  .** varies from 
d9f0: 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68  one VFS to anoth
da00: 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65  er, and from one
da10: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
da20: 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a  same VFS to the.
da30: 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
da40: 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
da50: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
da60: 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65   must be prepare
da70: 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20  d for any.** or 
da80: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74  all of these int
da90: 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55  erfaces to be NU
daa0: 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20  LL or for their 
dab0: 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e  behavior to chan
dac0: 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72  ge.** from one r
dad0: 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
dae0: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
daf0: 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d  s must not attem
db00: 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20  pt to access.** 
db10: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74  any of these met
db20: 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72  hods if the iVer
db30: 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20  sion of the VFS 
db40: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a  is less than 3..
db50: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
db60: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
db70: 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64  lite3_vfs;.typed
db80: 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
db90: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76  3_syscall_ptr)(v
dba0: 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c  oid);.struct sql
dbb0: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
dbc0: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
dbd0: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
dbe0: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
dbf0: 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20  r (currently 3) 
dc00: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
dc10: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
dc20: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
dc30: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
dc40: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
dc50: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
dc60: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
dc70: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
dc80: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
dc90: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
dca0: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
dcb0: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
dcc0: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
dcd0: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
dce0: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
dcf0: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
dd00: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
dd10: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
dd20: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
dd30: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
dd40: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
dd50: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
dd60: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
dd70: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
dd80: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
dd90: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
dda0: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
ddb0: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
ddc0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ddd0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
dde0: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
ddf0: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
de00: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
de10: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
de20: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
de30: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
de40: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
de50: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
de60: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
de70: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
de80: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
de90: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
dea0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
deb0: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
dec0: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
ded0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
dee0: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
def0: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
df00: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
df10: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
df20: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
df30: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
df40: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
df50: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
df60: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
df70: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
df80: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
df90: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
dfa0: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
dfb0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
dfc0: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
dfd0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
dfe0: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
dff0: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
e000: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
e010: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
e020: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
e030: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
e040: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
e050: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20  re in version 1 
e060: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
e070: 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65  s object.  ** de
e080: 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65  finition.  Those
e090: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65   that follow are
e0a0: 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f   added in versio
e0b0: 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a  n 2 or later.  *
e0c0: 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  /.  int (*xCurre
e0d0: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c  ntTimeInt64)(sql
e0e0: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74  ite3_vfs*, sqlit
e0f0: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a  e3_int64*);.  /*
e100: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
e110: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
e120: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20  ersions 1 and 2 
e130: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
e140: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54  s object..  ** T
e150: 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66  hose below are f
e160: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64  or version 3 and
e170: 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20   greater..  */. 
e180: 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65   int (*xSetSyste
e190: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
e1a0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e1b0: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
e1c0: 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20  syscall_ptr);.  
e1d0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
e1e0: 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d  ptr (*xGetSystem
e1f0: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
e200: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e210: 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20  zName);.  const 
e220: 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73  char *(*xNextSys
e230: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
e240: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e250: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a  r *zName);.  /*.
e260: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
e270: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
e280: 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68  rsions 1 through
e290: 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   3 of the sqlite
e2a0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
e2b0: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
e2c0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
e2d0: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
e2e0: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
e2f0: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
e300: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
e310: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
e320: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
e330: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
e340: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
e350: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
e360: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
e370: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
e380: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
e390: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
e3a0: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
e3b0: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
e3c0: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
e3d0: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
e3e0: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
e3f0: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
e400: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
e410: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
e420: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
e430: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
e440: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e450: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
e460: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
e470: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
e480: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
e490: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
e4a0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
e4b0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
e4c0: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
e4d0: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
e4e0: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
e4f0: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
e500: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
e510: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
e520: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
e530: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
e540: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
e550: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
e560: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
e570: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
e580: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
e590: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
e5a0: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
e5b0: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
e5c0: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
e5d0: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
e5e0: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
e5f0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
e600: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
e610: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
e620: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
e630: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
e640: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
e650: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
e660: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
e670: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
e680: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
e690: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
e6a0: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
e6b0: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
e6c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
e6d0: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
e6e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
e6f0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
e700: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
e710: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
e720: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
e730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
e740: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
e750: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
e760: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
e770: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
e780: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
e790: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
e7a0: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
e7b0: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
e7c0: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
e7d0: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
e7e0: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
e7f0: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
e800: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
e810: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
e820: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
e830: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
e840: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
e850: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
e860: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
e870: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
e880: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
e890: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
e8a0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
e8b0: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
e8c0: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
e8d0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
e8e0: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
e8f0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
e900: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
e910: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
e920: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
e930: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
e940: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
e950: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
e960: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
e970: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
e980: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
e990: 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f   on the correspo
e9a0: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
e9b0: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
e9c0: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
e9d0: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
e9e0: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
e9f0: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
ea00: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
ea10: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
ea20: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
ea30: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
ea40: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
ea50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ea60: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
ea70: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
ea80: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
ea90: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
eaa0: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
eab0: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
eac0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
ead0: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
eae0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
eaf0: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
eb00: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
eb10: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
eb20: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
eb30: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
eb40: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
eb50: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
eb60: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
eb70: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
eb80: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
eb90: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
eba0: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
ebb0: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
ebc0: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
ebd0: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
ebe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
ebf0: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
ec00: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
ec10: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
ec20: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
ec30: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
ec40: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ec50: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
ec60: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
ec70: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
ec80: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
ec90: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
eca0: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
ecb0: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
ecc0: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
ecd0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ece0: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
ecf0: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
ed00: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
ed10: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
ed20: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
ed30: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
ed40: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
ed50: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
ed60: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
ed70: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
ed80: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
ed90: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
eda0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
edb0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
edc0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
edd0: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
ede0: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
edf0: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
ee00: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
ee10: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
ee20: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
ee30: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
ee40: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
ee50: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
ee60: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
ee70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
ee80: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
ee90: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
eea0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
eeb0: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
eec0: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
eed0: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
eee0: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
eef0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
ef00: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
ef10: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
ef20: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
ef30: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
ef40: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
ef50: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
ef60: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
ef70: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
ef80: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ef90: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
efa0: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
efb0: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
efc0: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
efd0: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
efe0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
eff0: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
f000: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
f010: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
f020: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
f030: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
f040: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
f050: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
f060: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f070: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
f080: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
f090: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
f0a0: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
f0b0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f0c0: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
f0d0: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
f0e0: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
f0f0: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
f100: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
f110: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
f120: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
f130: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
f140: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
f150: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
f160: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
f170: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
f180: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
f190: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
f1a0: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
f1b0: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
f1c0: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
f1d0: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
f1e0: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
f1f0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
f200: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
f210: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
f220: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
f230: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
f240: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
f250: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
f260: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
f270: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
f280: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f290: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
f2a0: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
f2b0: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
f2c0: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
f2d0: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
f2e0: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
f2f0: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
f300: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
f310: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
f320: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
f330: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
f340: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f350: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
f360: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
f370: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
f380: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
f390: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
f3a0: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
f3b0: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
f3c0: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
f3d0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f3e0: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
f3f0: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
f400: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
f410: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
f420: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
f430: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
f440: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
f450: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
f460: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
f470: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
f480: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
f490: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
f4a0: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
f4b0: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
f4c0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
f4d0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
f4e0: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
f4f0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
f500: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
f510: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
f520: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f530: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
f540: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
f550: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
f560: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
f570: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
f580: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
f590: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
f5a0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
f5b0: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
f5c0: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
f5d0: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
f5e0: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
f5f0: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
f600: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f610: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
f620: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
f630: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
f640: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
f650: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
f660: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
f670: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
f680: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
f690: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
f6a0: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
f6b0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
f6c0: 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
f6d0: 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
f6e0: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
f6f0: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
f700: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
f710: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
f720: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
f730: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
f740: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
f750: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
f760: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
f770: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
f780: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
f790: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f7a0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
f7b0: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
f7c0: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
f7d0: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
f7e0: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
f7f0: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
f800: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
f810: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
f820: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
f830: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
f840: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
f850: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
f860: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
f870: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
f880: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
f890: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
f8a0: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
f8b0: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
f8c0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f8d0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
f8e0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
f8f0: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
f900: 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
f910: 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
f920: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
f930: 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
f940: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
f950: 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
f960: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f970: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
f980: 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
f990: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f9a0: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
f9b0: 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
f9c0: 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
f9d0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
f9e0: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
f9f0: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
fa00: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
fa10: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
fa20: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
fa30: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
fa40: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
fa50: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
fa60: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
fa70: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
fa80: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
fa90: 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
faa0: 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
fab0: 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
fac0: 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
fad0: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
fae0: 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
faf0: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
fb00: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
fb10: 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
fb20: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
fb30: 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
fb40: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
fb50: 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
fb60: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
fb70: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
fb80: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
fb90: 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
fba0: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
fbb0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
fbc0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
fbd0: 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
fbe0: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
fbf0: 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
fc00: 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
fc10: 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
fc20: 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
fc30: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fc40: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
fc50: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
fc60: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
fc70: 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
fc80: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
fc90: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
fca0: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
fcb0: 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
fcc0: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
fcd0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
fce0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
fcf0: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
fd00: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
fd10: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
fd20: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
fd30: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
fd40: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
fd50: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
fd60: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
fd70: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
fd80: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
fd90: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
fda0: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
fdb0: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
fdc0: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
fdd0: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
fde0: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
fdf0: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
fe00: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
fe10: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
fe20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
fe30: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
fe40: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
fe50: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
fe60: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
fe70: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
fe80: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
fe90: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
fea0: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
feb0: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
fec0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
fed0: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
fee0: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
fef0: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
ff00: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
ff10: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
ff20: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
ff30: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
ff40: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ff50: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
ff60: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
ff70: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
ff80: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
ff90: 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
ffa0: 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
ffb0: 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
ffc0: 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
ffd0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
ffe0: 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
fff0: 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
10000 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
10010 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
10020 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
10030 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
10040 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
10050 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
10060 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
10070 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
10080 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
10090 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
100a0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
100b0 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
100c0 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72  ger.** [configur
100d0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
100e0 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
100f0 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
10100 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
10110 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
10120 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
10130 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
10140 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f  nding on the [co
10150 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10160 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
10170 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
10180 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
10190 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
101a0 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
101b0 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
101c0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
101d0 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
101e0 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
101f0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
10200 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
10210 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
10220 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
10230 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
10240 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
10250 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
10260 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
10270 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
10280 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
10290 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  nections.**.** T
102a0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
102b0 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
102c0 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
102d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
102e0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
102f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10300 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
10310 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
10320 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
10330 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
10340 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
10350 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
10360 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
10370 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
10380 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
10390 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
103a0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
103b0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
103c0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
103d0 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
103e0 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
103f0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
10400 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
10410 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
10420 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
10430 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
10440 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
10450 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10460 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
10470 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
10480 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
10490 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
104a0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
104b0 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
104c0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
104d0 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
104e0 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
104f0 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
10500 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
10510 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
10520 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10530 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
10540 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
10550 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10560 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
10570 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
10580 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
10590 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
105a0 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
105b0 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
105c0 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
105d0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
105e0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
105f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
10600 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
10610 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
10620 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
10630 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
10640 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
10650 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
10660 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
10670 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
10680 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
10690 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
106a0 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
106b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
106c0 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
106d0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
106e0 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
106f0 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
10700 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
10710 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
10720 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
10730 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
10740 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
10750 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
10760 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
10770 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
10780 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
10790 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
107a0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
107b0 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
107c0 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
107d0 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
107e0 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
107f0 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
10800 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
10810 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
10820 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
10830 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
10840 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
10850 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
10860 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
10870 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
10880 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
10890 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
108a0 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
108b0 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
108c0 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
108d0 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
108e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
108f0 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
10900 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
10910 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
10920 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
10930 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
10940 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
10950 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
10960 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
10970 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
10980 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
10990 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
109a0 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
109b0 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
109c0 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
109d0 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
109e0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
109f0 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c   xMalloc, xReall
10a00 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65  oc, and xFree me
10a10 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
10a20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
10a30 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
10a40 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
10a50 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
10a60 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
10a70 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ..** ^SQLite gua
10a80 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
10a90 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
10aa0 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
10ab0 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
10ac0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
10ad0 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
10ae0 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53  oundup..**.** xS
10af0 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
10b00 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
10b10 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
10b20 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
10b30 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
10b40 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
10b50 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
10b60 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
10b70 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
10b80 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
10b90 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
10ba0 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
10bb0 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
10bc0 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
10bd0 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
10be0 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
10bf0 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
10c00 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
10c10 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
10c20 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
10c30 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
10c40 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
10c50 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
10c60 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
10c70 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
10c80 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
10c90 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
10ca0 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
10cb0 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
10cc0 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
10cd0 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
10ce0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10cf0 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
10d00 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
10d10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
10d20 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
10d30 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
10d40 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
10d50 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
10d60 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
10d70 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
10d80 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
10d90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
10da0 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
10db0 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
10dc0 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
10dd0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46  ry allocator.  F
10de0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
10df0 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
10e00 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
10e10 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
10e20 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
10e30 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
10e40 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
10e50 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
10e60 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
10e70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
10e80 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
10e90 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
10ea0 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
10eb0 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
10ec0 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
10ed0 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
10ee0 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
10ef0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
10f00 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
10f10 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
10f20 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
10f30 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
10f40 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
10f50 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
10f60 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
10f70 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
10f80 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
10f90 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
10fa0 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
10fb0 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
10fc0 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
10fd0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
10fe0 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
10ff0 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
11000 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
11010 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
11020 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
11030 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
11040 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
11050 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
11060 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
11070 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
11080 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
11090 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
110a0 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
110b0 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
110c0 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
110d0 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
110e0 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
110f0 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
11100 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
11110 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
11120 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
11130 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
11140 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
11150 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
11160 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
11170 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
11180 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
11190 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
111a0 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
111b0 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
111c0 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
111d0 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
111e0 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
111f0 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
11200 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
11210 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
11220 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11230 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
11240 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
11250 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
11260 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
11270 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
11280 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
11290 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
112a0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
112b0 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
112c0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
112d0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
112e0 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
112f0 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
11300 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
11310 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
11320 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
11330 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
11340 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
11350 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
11360 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
11370 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
11380 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
11390 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
113a0 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
113b0 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
113c0 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
113d0 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
113e0 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
113f0 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
11400 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
11410 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
11420 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11430 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
11440 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
11450 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
11460 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
11470 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
11480 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
11490 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
114a0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
114b0 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
114c0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
114d0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
114e0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
114f0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
11500 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11510 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
11520 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
11530 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11540 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
11550 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
11560 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
11570 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11580 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
11590 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
115a0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
115b0 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
115c0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
115d0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
115e0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
115f0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
11600 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
11610 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
11620 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
11630 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
11640 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
11650 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
11660 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
11670 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
11680 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
11690 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
116a0 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
116b0 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
116c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
116d0 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
116e0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
116f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11700 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
11710 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11720 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
11730 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
11740 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
11750 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
11760 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
11770 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
11780 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
11790 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
117a0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
117b0 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
117c0 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
117d0 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
117e0 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
117f0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
11800 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
11810 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
11820 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11830 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
11840 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11850 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
11860 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
11870 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
11880 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
11890 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
118a0 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
118b0 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
118c0 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
118d0 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
118e0 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
118f0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
11900 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
11910 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
11920 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
11930 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
11940 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
11950 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
11960 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11970 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
11980 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
11990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
119a0 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
119b0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
119c0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
119d0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
119e0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
119f0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
11a00 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
11a10 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
11a20 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
11a30 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
11a40 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
11a50 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
11a60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11a70 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
11a80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
11a90 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
11aa0 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
11ab0 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
11ac0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
11ad0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
11ae0 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
11af0 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
11b00 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
11b10 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
11b20 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
11b30 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
11b40 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
11b50 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
11b60 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
11b70 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
11b80 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
11b90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
11ba0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
11bb0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
11bc0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
11bd0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
11be0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
11bf0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
11c00 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
11c10 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
11c20 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
11c30 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
11c40 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
11c50 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
11c60 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11c70 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
11c80 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
11c90 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
11ca0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
11cb0 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
11cc0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11cd0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
11ce0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
11cf0 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
11d00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
11d10 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
11d20 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
11d30 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
11d40 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
11d50 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
11d60 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
11d70 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
11d80 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
11d90 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
11da0 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
11db0 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
11dc0 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
11dd0 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
11de0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11df0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
11e00 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
11e10 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
11e20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
11e30 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
11e40 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11e50 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
11e60 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
11e70 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
11e80 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
11e90 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
11ea0 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
11eb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
11ec0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
11ed0 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
11ee0 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
11ef0 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
11f00 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
11f10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11f20 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
11f30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11f40 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
11f50 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
11f60 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
11f70 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
11f80 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
11f90 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
11fa0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
11fb0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
11fc0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
11fd0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
11fe0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
11ff0 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
12000 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
12010 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
12020 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
12030 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
12040 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
12050 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
12060 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
12070 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
12080 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
12090 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
120a0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
120b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
120c0 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
120d0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
120e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
120f0 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
12100 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
12110 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
12120 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12130 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12140 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12150 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
12160 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
12170 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
12180 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
12190 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
121a0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
121b0 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
121c0 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
121d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
121e0 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
121f0 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
12200 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
12210 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
12220 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
12230 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12240 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
12250 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
12260 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
12270 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
12280 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
12290 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
122a0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
122b0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
122c0 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
122d0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
122e0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
122f0 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
12300 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
12310 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
12320 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
12330 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
12340 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12350 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
12360 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
12370 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
12380 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
12390 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
123a0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
123b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
123c0 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
123d0 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
123e0 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
123f0 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
12400 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12410 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
12420 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
12430 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
12440 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12450 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
12460 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
12470 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
12480 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12490 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
124a0 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
124b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
124c0 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
124d0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
124e0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70  FIG_MEMSTATUS op
124f0 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
12500 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
12510 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72  pe int,.** inter
12520 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
12530 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
12540 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
12550 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
12560 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
12570 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
12580 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
12590 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
125a0 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73  stics are.** dis
125b0 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f  abled, the follo
125c0 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
125d0 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
125e0 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
125f0 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
12600 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
12610 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
12620 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
12630 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
12640 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
12650 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
12660 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
12670 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
12680 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
12690 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
126a0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
126b0 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
126c0 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
126d0 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
126e0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
126f0 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
12700 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
12710 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
12720 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
12730 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
12740 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
12750 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
12760 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12770 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
12780 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12790 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
127a0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
127b0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74  NFIG_SCRATCH opt
127c0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
127d0 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
127e0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ffer.** that SQL
127f0 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20  ite can use for 
12800 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
12810 20 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72   ^(There are thr
12820 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  ee arguments.** 
12830 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
12840 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69  _SCRATCH:  A poi
12850 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
12860 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
12870 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
12880 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61  ch the scratch a
12890 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
128a0 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
128b0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
128c0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
128d0 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
128e0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
128f0 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
12900 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a  cations (N).)^.*
12910 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
12920 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
12930 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
12940 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
12950 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
12960 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
12970 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
12980 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20  te will not use 
12990 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63  more than one sc
129a0 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65  ratch buffers pe
129b0 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51  r thread..** ^SQ
129c0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
129d0 72 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63  request a scratc
129e0 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
129f0 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
12a00 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
12a10 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a  se page size..**
12a20 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64   ^If SQLite need
12a30 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  s needs addition
12a40 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  al.** scratch me
12a50 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
12a60 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
12a70 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
12a80 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
12a90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
12aa0 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
12ab0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
12ac0 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
12ad0 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  <p>.** ^When the
12ae0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f   application pro
12af0 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74  vides any amount
12b00 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f   of scratch memo
12b10 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49  ry using.** SQLI
12b20 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
12b30 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73  H, SQLite avoids
12b40 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72   unnecessary lar
12b50 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  ge.** [sqlite3_m
12b60 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63  alloc|heap alloc
12b70 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73  ations]..** This
12b80 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f   can help [Robso
12b90 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20  n proof|prevent 
12ba0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12bb0 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20  n failures] due 
12bc0 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d  to heap.** fragm
12bd0 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d  entation in low-
12be0 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20  memory embedded 
12bf0 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64  systems..** </dd
12c00 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12c10 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
12c20 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
12c30 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
12c40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
12c50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12c60 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e  PAGECACHE option
12c70 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
12c80 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
12c90 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  r.** that SQLite
12ca0 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65   can use for the
12cb0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
12cc0 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
12cd0 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61  fault page.** ca
12ce0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
12cf0 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
12d00 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
12d10 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
12d20 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
12d30 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
12d40 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
12d50 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
12d60 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
12d70 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
12d80 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
12d90 6e 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68  n option..** ^Th
12da0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
12db0 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
12dc0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
12dd0 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  HE: A pointer to
12de0 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e  .** 8-byte align
12df0 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  ed.** memory, th
12e00 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
12e10 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
12e20 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
12e30 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
12e40 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
12e50 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
12e60 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
12e70 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
12e80 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
12e90 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
12ea0 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20  and 65536) plus 
12eb0 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73  some extra bytes
12ec0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
12ed0 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
12ee0 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20  number of extra 
12ef0 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20  bytes needed by 
12f00 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a  the page header.
12f10 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
12f20 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ined using the [
12f30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
12f40 41 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69  ACHE_HDRSZ] opti
12f50 6f 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  on .** to [sqlit
12f60 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
12f70 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
12f80 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
12f90 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
12fa0 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61  ** for the sz pa
12fb0 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61  rameter to be la
12fc0 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73  rger than necess
12fd0 61 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a  ary.  The first.
12fe0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
12ff0 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ld pointer to an
13000 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
13010 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
13020 74 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65  that.** is at le
13030 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
13040 66 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77  f memory, otherw
13050 69 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 62  ise subsequent b
13060 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
13070 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c  defined..** ^SQL
13080 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
13090 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
130a0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
130b0 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66  gument to satisf
130c0 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20  y its.** memory 
130d0 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69  needs for the fi
130e0 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74  rst N pages that
130f0 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68   it adds to cach
13100 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  e.  ^If addition
13110 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
13120 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
13130 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
13140 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
13150 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a  s option, then.*
13160 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  * SQLite goes to
13170 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13180 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69  ()] for the addi
13190 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73  tional storage s
131a0 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  pace.</dd>.**.**
131b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
131c0 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
131d0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
131e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
131f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
13200 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  EAP option speci
13210 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
13220 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20  mory buffer .** 
13230 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
13240 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
13250 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
13260 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
13270 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68  eds.** beyond th
13280 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72  ose provided for
13290 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
132a0 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a  IG_SCRATCH] and.
132b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
132c0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
132d0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
132e0 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
132f0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
13300 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
13310 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
13320 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
13330 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
13340 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
13350 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65  _MEMSYS5] and re
13360 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
13370 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b  _ERROR] if invok
13380 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
13390 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
133a0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
133b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
133c0 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20  P:.** An 8-byte 
133d0 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
133e0 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
133f0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
13400 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
13410 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
13420 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
13430 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
13440 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
13450 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
13460 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
13470 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
13480 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
13490 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
134a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
134b0 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
134c0 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
134d0 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
134e0 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
134f0 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
13500 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
13510 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
13520 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
13530 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68  not NULL then th
13540 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
13550 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
13560 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
13570 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
13580 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
13590 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
135a0 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
135b0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
135c0 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
135d0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
135e0 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
135f0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
13600 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
13610 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
13620 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
13630 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
13640 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
13650 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
13660 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
13670 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
13680 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
13690 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
136a0 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
136b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
136c0 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
136d0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
136e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
136f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13700 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  _MUTEX option ta
13710 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
13720 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
13730 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
13740 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
13750 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
13760 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
13770 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
13780 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61  ment specifies a
13790 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
137a0 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
137b0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a  nes to be used.*
137c0 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d  * in place the m
137d0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
137e0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
137f0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
13800 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
13810 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
13820 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
13830 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
13840 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
13850 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
13860 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
13870 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
13880 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13890 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
138a0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
138b0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
138c0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
138d0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
138e0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
138f0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
13900 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
13910 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
13920 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
13930 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13940 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
13950 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
13960 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13970 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
13980 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
13990 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
139a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
139b0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
139c0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
139d0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
139e0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
139f0 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69  IG_GETMUTEX opti
13a00 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
13a10 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
13a20 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
13a30 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
13a40 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
13a50 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
13a60 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
13a70 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
13a80 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
13a90 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
13aa0 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
13ab0 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
13ac0 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
13ad0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
13ae0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
13af0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
13b00 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
13b10 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
13b20 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
13b30 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
13b40 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
13b50 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
13b60 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
13b70 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
13b80 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
13b90 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
13ba0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
13bb0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
13bc0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
13bd0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
13be0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
13bf0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
13c00 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
13c10 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
13c20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
13c30 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
13c40 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
13c50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13c60 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
13c70 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
13c80 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
13c90 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
13ca0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13cb0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
13cc0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
13cd0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
13ce0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13cf0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13d00 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f  _LOOKASIDE optio
13d10 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
13d20 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
13d30 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61  mine.** the defa
13d40 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b  ult size of look
13d50 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20  aside memory on 
13d60 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
13d70 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
13d80 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13d90 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
13da0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
13db0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
13dc0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
13dd0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
13de0 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
13df0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
13e00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
13e10 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49    ^(SQLITE_CONFI
13e20 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73  G_LOOKASIDE.** s
13e30 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75  ets the <i>defau
13e40 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
13e50 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
13e60 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
13e70 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e  ASIDE].** option
13e80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
13e90 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
13ea0 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
13eb0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
13ec0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13ed0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
13ee0 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
13ef0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13f00 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
13f10 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13f20 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
13f30 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
13f40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13f50 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
13f60 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13f70 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
13f80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13f90 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
13fa0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
13fb0 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
13fc0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
13fd0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20   interface to a 
13fe0 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
13ff0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
14000 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d  .)^.** ^SQLite m
14010 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
14020 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  he [sqlite3_pcac
14030 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14040 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
14050 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14060 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
14070 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
14080 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
14090 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
140a0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
140b0 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
140c0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
140d0 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
140e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
140f0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
14100 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
14110 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
14120 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72  s of.** the curr
14130 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ent page cache i
14140 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
14150 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
14160 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
14170 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14180 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
14190 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
141a0 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
141b0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
141c0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
141d0 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
141e0 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
141f0 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
14200 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14210 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
14220 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
14230 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
14240 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
14250 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
14260 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
14270 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
14280 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
14290 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
142a0 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
142b0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
142c0 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
142d0 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
142e0 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
142f0 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
14300 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
14310 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
14320 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
14330 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
14340 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
14350 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
14360 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
14370 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
14380 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
14390 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
143a0 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
143b0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
143c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
143d0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
143e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
143f0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
14400 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
14410 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
14420 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
14430 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
14440 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
14450 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
14460 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
14470 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
14480 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
14490 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
144a0 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
144b0 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
144c0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
144d0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
144e0 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
144f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
14500 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
14510 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
14520 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
14530 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
14540 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
14550 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
14560 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
14570 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
14580 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
14590 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
145a0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
145b0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
145c0 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
145d0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
145e0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
145f0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
14600 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
14610 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
14620 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
14630 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
14640 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14650 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
14660 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14670 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54  G_URI.** <dd>^(T
14680 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14690 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _URI option take
146a0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
146b0 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
146c0 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  .** If non-zero,
146d0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
146e0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
146f0 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
14700 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
14710 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61  ,.** then URI ha
14720 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
14730 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
14740 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
14750 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65  is globally.** e
14760 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
14770 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20  names passed to 
14780 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
14790 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
147a0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
147b0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
147c0 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
147d0 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
147e0 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
147f0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
14800 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
14810 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
14820 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
14830 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
14840 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
14850 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
14860 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
14870 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c  ^If it is global
14880 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
14890 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
148a0 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
148b0 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
148c0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
148d0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
148e0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
148f0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
14900 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c  ned. ^(By defaul
14910 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
14920 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
14930 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
14940 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
14950 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
14960 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
14970 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
14980 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
14990 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ed.)^.**.** [[SQ
149a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
149b0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
149c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
149d0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
149e0 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e  EX_SCAN.** <dd>^
149f0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14a00 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
14a10 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b  _SCAN option tak
14a20 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
14a30 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ger.** argument 
14a40 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
14a50 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
14a60 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
14a70 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a  able or disable.
14a80 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  ** the use of co
14a90 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
14aa0 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
14ab0 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
14ac0 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e   optimizer..** ^
14ad0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
14ae0 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
14af0 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
14b00 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
14b10 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
14b20 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14b30 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
14b40 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
14b50 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
14b60 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
14b70 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
14b80 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
14b90 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
14ba0 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
14bb0 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
14bc0 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
14bd0 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
14be0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
14bf0 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
14c00 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
14c10 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
14c20 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
14c30 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
14c40 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
14c50 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
14c60 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
14c70 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
14c80 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
14c90 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
14ca0 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
14cb0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
14cc0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
14cd0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
14ce0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14cf0 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
14d00 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14d10 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
14d20 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14d30 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
14d40 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
14d50 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
14d60 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
14d70 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
14d80 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
14d90 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
14da0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
14db0 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
14dc0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
14dd0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14de0 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
14df0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
14e00 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
14e10 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
14e20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
14e30 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
14e40 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
14e50 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
14e60 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
14e70 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
14e80 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
14e90 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
14ea0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
14eb0 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
14ec0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
14ed0 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
14ee0 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
14ef0 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
14f00 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
14f10 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
14f20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
14f30 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
14f40 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
14f50 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
14f60 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
14f70 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
14f80 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
14f90 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
14fa0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
14fb0 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
14fc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14fd0 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
14fe0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
14ff0 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
15000 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
15010 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
15020 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
15030 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
15040 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
15050 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
15060 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
15070 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
15080 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
15090 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
150a0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
150b0 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
150c0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
150d0 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
150e0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
150f0 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
15100 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
15110 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
15120 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
15130 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
15140 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
15150 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
15160 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
15170 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
15180 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
15190 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
151a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
151b0 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
151c0 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
151d0 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
151e0 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
151f0 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
15200 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
15210 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15220 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
15230 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15240 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
15250 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
15260 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
15270 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
15280 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
15290 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
152a0 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
152b0 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
152c0 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
152d0 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
152e0 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
152f0 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
15300 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
15310 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
15320 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
15330 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
15340 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
15350 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15360 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
15370 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
15380 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
15390 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
153a0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
153b0 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
153c0 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
153d0 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
153e0 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
153f0 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79  will be silently
15400 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65   truncated if ne
15410 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20  cessary so that 
15420 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65  it does not exce
15430 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ed the.** compil
15440 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
15450 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
15460 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
15470 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
15480 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
15490 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
154a0 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
154b0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
154c0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
154d0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
154e0 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
154f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
15500 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
15510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15520 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
15530 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15540 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15550 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
15560 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15570 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e  _HEAPSIZE option
15580 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
15590 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a  le if SQLite is.
155a0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  ** compiled for 
155b0 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65  Windows with the
155c0 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
155d0 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
155e0 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65  ssor macro.** de
155f0 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43  fined. ^SQLITE_C
15600 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
15610 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d  SIZE takes a 32-
15620 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
15630 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68  eger value.** th
15640 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
15650 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
15660 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61   the created hea
15670 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  p..** </dl>.**.*
15680 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15690 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d  G_PCACHE_HDRSZ]]
156a0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
156b0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
156c0 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
156d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
156e0 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e  CHE_HDRSZ option
156f0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15700 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
15710 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
15720 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  to an integer an
15730 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68  d writes into th
15740 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e  at integer the n
15750 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a  umber of extra.*
15760 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65  * bytes per page
15770 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61   required for ea
15780 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49  ch page in [SQLI
15790 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
157a0 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f  CHE]..** The amo
157b0 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61  unt of extra spa
157c0 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20  ce required can 
157d0 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67  change depending
157e0 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72   on the compiler
157f0 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74  ,.** target plat
15800 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65  form, and SQLite
15810 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20   version..**.** 
15820 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15830 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PMASZ]].** <dt>S
15840 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
15850 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
15860 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
15870 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
15880 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
15890 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
158a0 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  n unsigned integ
158b0 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20  er and sets the 
158c0 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a  "Minimum PMA Siz
158d0 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69  e" for the multi
158e0 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74  threaded.** sort
158f0 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67  er to that integ
15900 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  er.  The default
15910 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a   minimum PMA Siz
15920 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a  e is set by the.
15930 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45  ** [SQLITE_SORTE
15940 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65  R_PMASZ] compile
15950 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e  -time option.  N
15960 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c  ew threads are l
15970 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65  aunched.** to he
15980 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65  lp with sort ope
15990 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c  rations when mul
159a0 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69  tithreaded sorti
159b0 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64  ng.** is enabled
159c0 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41   (using the [PRA
159d0 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d  GMA threads] com
159e0 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d  mand) and the am
159f0 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a  ount of content.
15a00 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20  ** to be sorted 
15a10 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65  exceeds the page
15a20 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20   size times the 
15a30 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a  minimum of the.*
15a40 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f  * [PRAGMA cache_
15a50 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e  size] setting an
15a60 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a  d this value..**
15a70 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
15a80 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15a90 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
15aa0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
15ab0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15ac0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
15ad0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
15ae0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15af0 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
15b00 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
15b10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15b20 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
15b30 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
15b40 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
15b50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15b60 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
15b70 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
15b80 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
15b90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15ba0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
15bb0 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
15bc0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
15bd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15be0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
15bf0 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
15c00 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
15c10 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
15c20 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
15c30 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
15c40 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
15c50 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
15c60 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15c70 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
15c80 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
15c90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15ca0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
15cb0 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
15cc0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
15cd0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
15ce0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
15cf0 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
15d00 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
15d10 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
15d20 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
15d30 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
15d40 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
15d50 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
15d60 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15d70 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
15d80 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
15d90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15da0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
15db0 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70      14  /* no-op
15dc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15dd0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
15de0 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f  CHE    15  /* no
15df0 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
15e00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
15e10 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
15e20 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
15e30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15e40 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
15e50 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
15e60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15e70 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
15e80 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69       18  /* sqli
15e90 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
15ea0 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
15eb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15ec0 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f  TPCACHE2   19  /
15ed0 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
15ee0 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
15ef0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15f00 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
15f10 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69  EX_SCAN 20  /* i
15f20 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
15f30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
15f40 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20  OG       21  /* 
15f50 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a  xSqllog, void* *
15f60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15f70 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
15f80 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69  E    22  /* sqli
15f90 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74  te3_int64, sqlit
15fa0 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66  e3_int64 */.#def
15fb0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15fc0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15fd0 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74        23  /* int
15fe0 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e   nByte */.#defin
15ff0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16000 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20  PCACHE_HDRSZ    
16010 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a      24  /* int *
16020 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  psz */.#define S
16030 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
16040 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  SZ              
16050 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64   25  /* unsigned
16060 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f   int szPma */../
16070 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
16080 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
16090 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
160a0 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
160b0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
160c0 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
160d0 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
160e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
160f0 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
16100 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
16110 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
16120 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
16130 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
16140 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
16150 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
16160 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
16170 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
16180 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
16190 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
161a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
161b0 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
161c0 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
161d0 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
161e0 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
161f0 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
16200 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
16210 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
16220 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
16230 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
16240 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
16250 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
16260 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
16270 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
16280 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
16290 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
162a0 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
162b0 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
162c0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
162d0 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
162e0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
162f0 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
16300 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
16310 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
16320 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
16330 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
16340 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
16350 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
16360 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
16370 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
16380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
16390 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
163a0 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
163b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
163c0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
163d0 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
163e0 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
163f0 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
16400 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
16410 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
16420 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
16430 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
16440 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16450 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
16460 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
16470 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
16480 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
16490 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
164a0 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
164b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
164c0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
164d0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
164e0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
164f0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
16500 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
16510 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
16520 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
16530 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
16540 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
16550 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16560 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
16570 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
16580 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
16590 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
165a0 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
165b0 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
165c0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
165d0 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
165e0 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
165f0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
16600 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
16610 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
16620 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
16630 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
16640 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
16650 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
16660 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
16670 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
16680 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
16690 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
166a0 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
166b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
166c0 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
166d0 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
166e0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
166f0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
16700 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
16710 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
16720 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
16730 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
16740 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
16750 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
16760 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
16770 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
16780 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
16790 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
167a0 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
167b0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
167c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
167d0 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
167e0 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
167f0 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
16800 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
16810 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
16820 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
16830 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
16840 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
16850 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
16860 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
16870 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
16880 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
16890 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
168a0 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
168b0 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
168c0 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
168d0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
168e0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
168f0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
16900 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
16910 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
16920 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
16930 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
16940 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
16950 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
16960 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
16970 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
16980 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
16990 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
169a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
169b0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
169c0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
169d0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
169e0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
169f0 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
16a00 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
16a10 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
16a20 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
16a30 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16a40 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
16a50 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
16a60 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
16a70 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
16a80 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
16a90 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
16aa0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
16ab0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
16ac0 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e  BLE_TRIGGER</dt>
16ad0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
16ae0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
16af0 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
16b00 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  le [CREATE TRIGG
16b10 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a  ER | triggers]..
16b20 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
16b30 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
16b40 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
16b50 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
16b60 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
16b70 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
16b80 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c  isable triggers,
16b90 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
16ba0 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20  enable triggers 
16bb0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
16bc0 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
16bd0 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
16be0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16bf0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
16c00 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
16c10 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
16c20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
16c30 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
16c40 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20  er triggers are 
16c50 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
16c60 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
16c70 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
16c80 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
16c90 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
16ca0 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
16cb0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72  hich case the tr
16cc0 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73  igger setting is
16cd0 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
16ce0 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
16cf0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
16d00 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
16d10 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
16d20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
16d30 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
16d40 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
16d50 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20  IG_ENABLE_FKEY  
16d60 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20     1002  /* int 
16d70 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
16d80 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16d90 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20  ENABLE_TRIGGER  
16da0 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1003  /* int int
16db0 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  * */.../*.** CAP
16dc0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
16dd0 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
16de0 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
16df0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
16e00 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
16e10 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
16e20 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
16e30 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
16e40 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
16e50 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
16e60 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74  SQLite. ^The ext
16e70 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
16e80 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
16e90 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
16ea0 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
16eb0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69  patibility..*/.i
16ec0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
16ed0 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
16ee0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
16ef0 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
16f00 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
16f10 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20  ert Rowid.**.** 
16f20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d  ^Each entry in m
16f30 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65  ost SQLite table
16f40 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57  s (except for [W
16f50 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
16f60 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75  bles).** has a u
16f70 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
16f80 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
16f90 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
16fa0 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
16fb0 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
16fc0 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
16fd0 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
16fe0 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
16ff0 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
17000 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
17010 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
17020 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
17030 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
17040 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
17050 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
17060 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
17070 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
17080 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
17090 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
170a0 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
170b0 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
170c0 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  id..**.** ^The s
170d0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
170e0 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65  rt_rowid(D) inte
170f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
17100 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
17110 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74   .** most recent
17120 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
17130 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69  ERT] into a rowi
17140 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74  d table or [virt
17150 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e  ual table].** on
17160 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17170 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65  tion D..** ^Inse
17180 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55  rts into [WITHOU
17190 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20  T ROWID] tables 
171a0 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64  are not recorded
171b0 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63  ..** ^If no succ
171c0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73  essful [INSERT]s
171d0 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c   into rowid tabl
171e0 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  es.** have ever 
171f0 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20  occurred on the 
17200 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17210 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20  ion D, .** then 
17220 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
17230 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74  ert_rowid(D) ret
17240 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
17250 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
17260 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
17270 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74  a trigger or wit
17280 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74  hin a [virtual t
17290 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c  able].** method,
172a0 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
172b0 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74  ne will return t
172c0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
172d0 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
172e0 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  w as long as the
172f0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
17300 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
17310 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
17320 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69  But once the tri
17330 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
17340 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64  table method end
17350 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
17360 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69  urned .** by thi
17370 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
17380 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73  s to what it was
17390 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
173a0 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a  ger or virtual.*
173b0 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62  * table method b
173c0 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41  egan.)^.**.** ^A
173d0 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20  n [INSERT] that 
173e0 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63  fails due to a c
173f0 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
17400 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20  ion is not a.** 
17410 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
17420 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  RT] and does not
17430 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
17440 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
17450 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
17460 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20  ^Thus INSERT OR 
17470 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
17480 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
17490 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
174a0 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
174b0 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
174c0 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
174d0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
174e0 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
174f0 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
17500 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e  ails.  ^(When IN
17510 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a  SERT OR REPLACE.
17520 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  ** encounters a 
17530 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
17540 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f  tion, it does no
17550 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20  t fail.  The.** 
17560 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73  INSERT continues
17570 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
17580 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f  fter deleting ro
17590 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ws that caused.*
175a0 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  * the constraint
175b0 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45   problem so INSE
175c0 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69  RT OR REPLACE wi
175d0 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65  ll always change
175e0 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76  .** the return v
175f0 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74  alue of this int
17600 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  erface.)^.**.** 
17610 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
17620 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
17630 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69  e, an [INSERT] i
17640 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
17650 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
17660 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
17670 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
17680 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
17690 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
176a0 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51  accessible to SQ
176b0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61  L statements via
176c0 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e   the.** [last_in
176d0 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c  sert_rowid() SQL
176e0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
176f0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
17700 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
17710 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f  a new [INSERT] o
17720 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61  n the same.** da
17730 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17740 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c  n while the [sql
17750 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
17760 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e  _rowid()].** fun
17770 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
17780 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
17790 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
177a0 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68  t [rowid],.** th
177b0 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
177c0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
177d0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
177e0 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70  wid()] is.** unp
177f0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
17800 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
17810 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
17820 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74   the new.** last
17830 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e   insert [rowid].
17840 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
17850 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
17860 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
17870 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
17880 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
17890 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
178a0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
178b0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
178c0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
178d0 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
178e0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a  ed, inserted or.
178f0 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  ** deleted by th
17900 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
17910 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
17920 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
17930 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
17940 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
17950 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69  connection speci
17960 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79  fied by the only
17970 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
17980 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
17990 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
179a0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
179b0 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61  ot modify the va
179c0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
179d0 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
179e0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68  ..**.** ^Only ch
179f0 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63  anges made direc
17a00 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52  tly by the INSER
17a10 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
17a20 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
17a30 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
17a40 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e  - auxiliary chan
17a50 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43  ges caused by [C
17a60 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
17a70 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b  triggers], .** [
17a80 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
17a90 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45  ons] or [REPLACE
17aa0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
17ab0 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20  olution are not 
17ac0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
17ad0 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
17ae0 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
17af0 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49  cepted by .** [I
17b00 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
17b10 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74  r | INSTEAD OF t
17b20 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74  riggers] are not
17b30 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76   counted. ^The v
17b40 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65  alue .** returne
17b50 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
17b60 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65  nges() immediate
17b70 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45  ly after an INSE
17b80 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a  RT, UPDATE or .*
17b90 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
17ba0 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77  nt run on a view
17bb0 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e   is always zero.
17bc0 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61   Only changes ma
17bd0 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74  de to real .** t
17be0 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65  ables are counte
17bf0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20  d..**.** Things 
17c00 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63  are more complic
17c10 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69  ated if the sqli
17c20 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
17c30 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65  nction is.** exe
17c40 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72  cuted while a tr
17c50 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73  igger program is
17c60 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d   running. This m
17c70 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65  ay happen if the
17c80 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
17c90 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
17ca0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f  SQL function], o
17cb0 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20  r if some other 
17cc0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
17cd0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c  tion invokes sql
17ce0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64  ite3_changes() d
17cf0 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69  irectly. Essenti
17d00 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c  ally:.** .** <ul
17d10 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65  >.**   <li> ^(Be
17d20 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20  fore entering a 
17d30 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
17d40 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17d50 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
17d60 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
17d70 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61  ) function is sa
17d80 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74  ved. After the t
17d90 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a  rigger program .
17da0 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69  **        has fi
17db0 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67  nished, the orig
17dc0 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65  inal value is re
17dd0 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a  stored.)^.** .**
17de0 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e     <li> ^(Within
17df0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
17e00 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20  am each INSERT, 
17e10 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54  UPDATE and DELET
17e20 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61  E .**        sta
17e30 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20  tement sets the 
17e40 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
17e50 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
17e60 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75  s() .**        u
17e70 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61  pon completion a
17e80 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75  s normal. Of cou
17e90 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20  rse, this value 
17ea0 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65  will not include
17eb0 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20   .**        any 
17ec0 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65  changes performe
17ed0 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72  d by sub-trigger
17ee0 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65  s, as the sqlite
17ef0 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
17f00 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c         value wil
17f10 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72  l be saved and r
17f20 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61  estored after ea
17f30 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68  ch sub-trigger h
17f40 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75  as run.)^.** </u
17f50 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20  l>.** .** ^This 
17f60 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68  means that if th
17f70 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  e changes() SQL 
17f80 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d  function (or sim
17f90 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a  ilar) is used.**
17fa0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e   by the first IN
17fb0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
17fc0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
17fd0 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
17fe0 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e  r, it .** return
17ff0 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73  s the value as s
18000 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c  et when the call
18010 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65  ing statement be
18020 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  gan executing..*
18030 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64  * ^If it is used
18040 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f   by the second o
18050 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63  r subsequent suc
18060 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  h statement with
18070 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a  in a trigger .**
18080 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61   program, the va
18090 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66  lue returned ref
180a0 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72  lects the number
180b0 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
180c0 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65  d by the .** pre
180d0 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50  vious INSERT, UP
180e0 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
180f0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
18100 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
18110 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
18120 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
18130 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
18140 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
18150 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
18160 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
18170 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
18180 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
18190 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
181a0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
181b0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
181c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
181d0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
181e0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
181f0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
18200 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
18210 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
18220 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
18230 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
18240 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
18250 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
18260 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
18270 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
18280 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
18290 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
182a0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f  n returns the to
182b0 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  tal number of ro
182c0 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64  ws inserted, mod
182d0 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65  ified or.** dele
182e0 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45  ted by all [INSE
182f0 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72  RT], [UPDATE] or
18300 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
18310 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a  ents completed.*
18320 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61  * since the data
18330 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18340 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c  was opened, incl
18350 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63  uding those exec
18360 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  uted as.** part 
18370 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  of trigger progr
18380 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20  ams. ^Executing 
18390 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
183a0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  f SQL statement.
183b0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65  ** does not affe
183c0 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ct the value ret
183d0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
183e0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
183f0 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65  ..** .** ^Change
18400 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  s made as part o
18410 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  f [foreign key a
18420 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c  ctions] are incl
18430 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63  uded in the.** c
18440 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20  ount, but those 
18450 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20  made as part of 
18460 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
18470 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
18480 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67  e.** not. ^Chang
18490 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
184a0 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65  t are intercepte
184b0 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20  d by INSTEAD OF 
184c0 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65  triggers .** are
184d0 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   not counted..**
184e0 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68   .** See also th
184f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
18500 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
18510 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
18520 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
18530 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
18540 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
18550 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
18560 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
18570 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
18580 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
18590 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
185a0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
185b0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
185c0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
185d0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
185e0 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
185f0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
18600 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
18610 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
18620 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
18630 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
18640 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
18650 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
18660 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68   Query.**.** ^Th
18670 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
18680 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
18690 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
186a0 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
186b0 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
186c0 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
186d0 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
186e0 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
186f0 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
18700 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
18710 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
18720 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
18730 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
18740 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
18750 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
18760 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
18770 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
18780 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
18790 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
187a0 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
187b0 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
187c0 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
187d0 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
187e0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
187f0 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
18800 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
18810 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
18820 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
18830 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
18840 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
18850 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
18860 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
18870 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
18880 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
18890 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
188a0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
188b0 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
188c0 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
188d0 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
188e0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
188f0 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
18900 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
18910 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
18920 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
18930 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
18940 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
18950 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
18960 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
18970 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
18980 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
18990 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
189a0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
189b0 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
189c0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
189d0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
189e0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
189f0 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
18a00 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
18a10 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
18a20 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
18a30 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
18a40 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
18a50 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
18a60 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18a70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
18a80 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
18a90 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
18aa0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
18ab0 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
18ac0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
18ad0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
18ae0 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
18af0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
18b00 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
18b10 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18b20 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
18b30 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
18b40 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
18b50 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
18b60 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
18b70 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
18b80 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
18b90 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
18ba0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
18bb0 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
18bc0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
18bd0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
18be0 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
18bf0 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
18c00 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
18c10 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
18c20 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
18c30 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
18c40 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
18c50 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
18c60 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
18c70 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
18c80 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
18c90 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
18ca0 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
18cb0 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
18cc0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
18cd0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
18ce0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
18cf0 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
18d00 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
18d10 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
18d20 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
18d30 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
18d40 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
18d50 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
18d60 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
18d70 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
18d80 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
18d90 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
18da0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18db0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
18dc0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
18dd0 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
18de0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
18df0 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
18e00 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
18e10 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
18e20 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
18e30 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
18e40 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
18e50 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
18e60 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
18e70 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
18e80 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
18e90 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
18ea0 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
18eb0 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
18ec0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
18ed0 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
18ee0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
18ef0 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
18f00 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
18f10 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
18f20 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
18f30 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
18f40 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
18f50 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
18f60 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
18f70 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
18f80 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
18f90 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
18fa0 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
18fb0 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
18fc0 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
18fd0 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
18fe0 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
18ff0 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
19000 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
19010 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
19020 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
19030 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
19040 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
19050 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
19060 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
19070 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
19080 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
19090 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
190a0 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
190b0 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
190c0 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
190d0 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
190e0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
190f0 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
19100 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
19110 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
19120 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
19130 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
19140 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
19150 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
19160 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
19170 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
19180 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
19190 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
191a0 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
191b0 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
191c0 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
191d0 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
191e0 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
191f0 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
19200 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
19210 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
19220 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
19230 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
19240 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
19250 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
19260 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
19270 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
19280 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
19290 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
192a0 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
192b0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
192c0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
192d0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
192e0 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
192f0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
19300 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
19310 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
19320 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
19330 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
19340 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
19350 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
19360 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
19370 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
19380 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
19390 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
193a0 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
193b0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
193c0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
193d0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
193e0 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
193f0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
19400 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
19410 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
19420 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
19430 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
19440 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
19450 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
19460 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
19470 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
19480 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79   KEYWORDS: {busy
19490 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
194a0 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72  k} {busy handler
194b0 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  }.**.** ^The sql
194c0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
194d0 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65  r(D,X,P) routine
194e0 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
194f0 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74   function X.** t
19500 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
19510 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
19520 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
19530 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
19540 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20  ade to access a 
19550 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
19560 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
19570 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
19580 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61  ection] D when a
19590 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
195a0 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
195b0 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64  the table locked
195c0 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
195d0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20  _busy_handler() 
195e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
195f0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a  d to implement.*
19600 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  * [sqlite3_busy_
19610 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b  timeout()] and [
19620 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
19630 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  out]..**.** ^If 
19640 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
19650 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
19660 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
19670 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
19680 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
19690 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
196a0 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
196b0 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
196c0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
196d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
196e0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
196f0 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
19700 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
19710 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
19720 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19730 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
19740 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
19750 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
19760 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
19770 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
19780 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
19790 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
197a0 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
197b0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
197c0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
197d0 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
197e0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
197f0 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
19800 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20   previously for 
19810 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67  the same locking
19820 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
19830 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
19840 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
19850 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
19860 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
19870 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
19880 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
19890 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73  [SQLITE_BUSY] is
198a0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20   returned.** to 
198b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
198c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
198d0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
198e0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
198f0 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
19900 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
19910 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
19920 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
19930 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
19940 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
19950 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
19960 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
19970 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
19980 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
19990 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
199a0 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
199b0 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
199c0 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
199d0 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
199e0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
199f0 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
19a00 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
19a10 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
19a20 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61  USY].** to the a
19a30 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65  pplication inste
19a40 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
19a50 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  he .** busy hand
19a60 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
19a70 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
19a80 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
19a90 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
19aa0 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
19ab0 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
19ac0 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
19ad0 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
19ae0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
19af0 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
19b00 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
19b10 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
19b20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
19b30 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
19b40 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
19b50 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
19b60 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
19b70 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
19b80 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
19b90 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
19ba0 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
19bb0 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
19bc0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
19bd0 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
19be0 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
19bf0 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
19c00 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
19c10 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
19c20 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
19c30 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
19c40 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
19c50 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
19c60 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
19c70 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
19c80 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
19c90 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
19ca0 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
19cb0 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
19cc0 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
19cd0 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
19ce0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
19cf0 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
19d00 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
19d10 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
19d20 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
19d30 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
19d40 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
19d50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19d60 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
19d70 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
19d80 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
19d90 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
19da0 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
19db0 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
19dc0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
19dd0 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61  out()].** or eva
19de0 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20  luating [PRAGMA 
19df0 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20  busy_timeout=N] 
19e00 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a  will change the.
19e10 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ** busy handler 
19e20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61  and thus clear a
19e30 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ny previously se
19e40 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  t busy handler..
19e50 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
19e60 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
19e70 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
19e80 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
19e90 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
19ea0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
19eb0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
19ec0 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f  y handler.  In o
19ed0 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74  ther words,.** t
19ee0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
19ef0 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
19f00 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
19f10 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
19f20 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
19f30 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
19f40 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
19f50 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
19f60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19f70 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
19f80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
19f90 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
19fa0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
19fb0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
19fc0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
19fd0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
19fe0 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
19ff0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
1a000 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
1a010 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1a020 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
1a030 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1a040 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
1a050 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
1a060 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
1a070 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
1a080 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
1a090 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
1a0a0 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
1a0b0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
1a0c0 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
1a0d0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1a0e0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
1a0f0 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
1a100 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
1a110 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1a120 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1a130 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
1a140 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
1a150 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
1a160 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
1a170 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
1a180 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  _BUSY]..**.** ^C
1a190 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
1a1a0 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
1a1b0 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
1a1c0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
1a1d0 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
1a1e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
1a1f0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1a200 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1a210 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1a220 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
1a230 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1a240 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79  nnection] at any
1a250 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
1a260 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
1a270 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
1a280 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
1a290 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1a2a0 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
1a2b0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
1a2c0 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
1a2d0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1a2e0 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
1a2f0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1a300 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74    [PRAGMA busy_t
1a310 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73  imeout].*/.int s
1a320 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1a330 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
1a340 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
1a350 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
1a360 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
1a370 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
1a380 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
1a390 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
1a3a0 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
1a3b0 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
1a3c0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1a3d0 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
1a3e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
1a3f0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
1a400 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
1a410 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
1a420 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
1a430 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
1a440 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
1a450 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1a460 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
1a470 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
1a480 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
1a490 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
1a4a0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
1a4b0 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
1a4c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
1a4d0 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
1a4e0 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
1a4f0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
1a500 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
1a510 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
1a520 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
1a530 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
1a540 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
1a550 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
1a560 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
1a570 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
1a580 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
1a590 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1a5a0 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
1a5b0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1a5c0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
1a5d0 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
1a5e0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1a5f0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
1a600 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
1a610 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
1a620 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
1a630 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
1a640 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
1a650 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1a660 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
1a670 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
1a680 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
1a690 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
1a6a0 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
1a6b0 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
1a6c0 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
1a6d0 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
1a6e0 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
1a6f0 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
1a700 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
1a710 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1a720 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
1a730 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
1a740 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
1a750 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
1a760 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1a770 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
1a780 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
1a790 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
1a7a0 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
1a7b0 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
1a7c0 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
1a7d0 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
1a7e0 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
1a7f0 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
1a800 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
1a810 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1a820 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
1a830 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
1a840 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
1a850 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
1a860 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
1a870 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
1a880 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1a890 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1a8a0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
1a8b0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
1a8c0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
1a8d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
1a8e0 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
1a8f0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
1a900 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
1a910 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
1a920 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
1a930 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1a940 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1a950 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
1a960 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
1a970 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
1a980 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
1a990 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
1a9a0 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
1a9b0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
1a9c0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
1a9d0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
1a9e0 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
1a9f0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
1aa00 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
1aa10 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1aa20 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1aa30 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
1aa40 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
1aa50 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1aa60 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
1aa70 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1aa80 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
1aa90 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1aaa0 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
1aab0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
1aac0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
1aad0 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
1aae0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1aaf0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
1ab00 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1ab10 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
1ab20 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1ab30 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
1ab40 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1ab50 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1ab60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
1ab70 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
1ab80 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
1ab90 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
1aba0 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
1abb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1abc0 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
1abd0 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
1abe0 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
1abf0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
1ac00 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
1ac10 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
1ac20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
1ac30 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
1ac40 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
1ac50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1ac60 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1ac70 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
1ac80 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
1ac90 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
1aca0 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
1acb0 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
1acc0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
1acd0 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
1ace0 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
1acf0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
1ad00 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
1ad10 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
1ad20 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1ad30 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
1ad40 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
1ad50 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
1ad60 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
1ad70 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
1ad80 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
1ad90 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
1ada0 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
1adb0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1adc0 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
1add0 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
1ade0 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
1adf0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
1ae00 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1ae10 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
1ae20 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
1ae30 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
1ae40 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
1ae50 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
1ae60 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1ae70 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
1ae80 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
1ae90 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
1aea0 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
1aeb0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
1aec0 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
1aed0 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
1aee0 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
1aef0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
1af00 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
1af10 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
1af20 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
1af30 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
1af40 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
1af50 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
1af60 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
1af70 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
1af80 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1af90 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
1afa0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1afb0 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  sg()]..*/.int sq
1afc0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1afd0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1afe0 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
1aff0 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
1b000 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1b010 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
1b020 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
1b030 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
1b040 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
1b050 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
1b060 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
1b070 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
1b080 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1b090 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
1b0a0 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
1b0b0 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
1b0c0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1b0d0 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
1b0e0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
1b0f0 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
1b100 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
1b110 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
1b120 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1b130 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1b140 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1b150 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1b160 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1b170 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1b180 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1b190 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1b1a0 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1b1b0 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1b1c0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1b1d0 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1b1e0 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65   library..** The
1b1f0 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65  se routines unde
1b200 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74  rstand most of t
1b210 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f  he common K&R fo
1b220 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1b230 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61  ,.** plus some a
1b240 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74  dditional non-st
1b250 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20  andard formats, 
1b260 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a  detailed below..
1b270 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d  ** Note that som
1b280 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62  e of the more ob
1b290 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67  scure formatting
1b2a0 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65   options from re
1b2b0 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72  cent.** C-librar
1b2c0 79 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20  y standards are 
1b2d0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69  omitted from thi
1b2e0 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1b2f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1b300 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
1b310 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
1b320 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
1b330 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
1b340 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
1b350 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1b360 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1b370 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
1b380 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
1b390 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
1b3a0 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
1b3b0 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
1b3c0 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
1b3d0 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
1b3e0 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
1b3f0 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
1b400 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
1b410 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1b420 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
1b430 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
1b440 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
1b450 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
1b460 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
1b470 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
1b480 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
1b490 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
1b4a0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1b4b0 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
1b4c0 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
1b4d0 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
1b4e0 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
1b4f0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
1b500 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
1b510 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
1b520 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
1b530 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
1b540 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
1b550 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
1b560 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
1b570 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
1b580 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
1b590 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
1b5a0 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
1b5b0 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
1b5c0 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
1b5d0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1b5e0 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
1b5f0 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
1b600 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
1b610 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1b620 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
1b630 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
1b640 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
1b650 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
1b660 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
1b670 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
1b680 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
1b690 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
1b6a0 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
1b6b0 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
1b6c0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
1b6d0 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
1b6e0 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
1b6f0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
1b700 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1b710 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
1b720 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
1b730 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
1b740 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
1b750 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
1b760 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
1b770 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1b780 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
1b790 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
1b7a0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
1b7b0 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
1b7c0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
1b7d0 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
1b7e0 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
1b7f0 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
1b800 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
1b810 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
1b820 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
1b830 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
1b840 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
1b850 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
1b860 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
1b870 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
1b880 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1b890 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
1b8a0 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
1b8b0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1b8c0 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  intf()..**.** Th
1b8d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
1b8e0 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
1b8f0 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
1b900 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
1b910 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
1b920 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
1b930 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
1b940 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
1b950 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
1b960 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1b970 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
1b980 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
1b990 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
1b9a0 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22  ", "%w" and "%z"
1b9b0 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
1b9c0 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  ^(The %q option 
1b9d0 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
1b9e0 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
1b9f0 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69  utes a nul-termi
1ba00 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1ba10 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
1ba20 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
1ba30 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
1ba40 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
1ba50 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
1ba60 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
1ba70 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
1ba80 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62  eral.)^  By doub
1ba90 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
1baa0 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
1bab0 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
1bac0 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
1bad0 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
1bae0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
1baf0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
1bb00 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
1bb10 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
1bb20 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
1bb30 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
1bb40 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1bb50 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1bb60 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
1bb70 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1bb80 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
1bb90 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1bba0 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
1bbb0 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
1bbc0 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
1bbd0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1bbe0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1bbf0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1bc00 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1bc10 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1bc20 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
1bc30 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1bc40 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1bc50 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1bc60 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1bc70 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1bc80 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1bc90 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
1bca0 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
1bcb0 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
1bcc0 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
1bcd0 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
1bce0 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
1bcf0 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
1bd00 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1bd10 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1bd20 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1bd30 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1bd40 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
1bd50 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
1bd60 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1bd70 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
1bd80 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
1bd90 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
1bda0 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
1bdb0 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
1bdc0 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
1bdd0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
1bde0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1bdf0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1be00 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
1be10 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
1be20 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1be30 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1be40 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
1be50 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
1be60 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
1be70 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
1be80 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
1be90 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
1bea0 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
1beb0 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
1bec0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1bed0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20  .**.** ^(The %Q 
1bee0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1bef0 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
1bf00 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
1bf10 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
1bf20 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
1bf30 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
1bf40 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
1bf50 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1bf60 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
1bf70 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
1bf80 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
1bf90 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
1bfa0 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
1bfb0 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
1bfc0 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66  uotes).)^  So, f
1bfd0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
1bfe0 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
1bff0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1c000 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1c010 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1c020 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1c030 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
1c040 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1c050 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1c060 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1c070 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1c080 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1c090 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1c0a0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
1c0b0 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
1c0c0 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
1c0d0 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
1c0e0 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
1c0f0 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
1c100 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
1c110 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1c120 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20  *.** ^(The "%w" 
1c130 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1c140 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65  n is like "%q" e
1c150 78 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78  xcept that it ex
1c160 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63  pects to.** be c
1c170 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20  ontained within 
1c180 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e  double-quotes in
1c190 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20  stead of single 
1c1a0 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a  quotes, and it.*
1c1b0 2a 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f  * escapes the do
1c1c0 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61  uble-quote chara
1c1d0 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  cter instead of 
1c1e0 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65  the single-quote
1c1f0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e  .** character.)^
1c200 20 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61    The "%w" forma
1c210 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
1c220 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66  intended for saf
1c230 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a  ely inserting.**
1c240 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d   table and colum
1c250 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63  n names into a c
1c260 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73  onstructed SQL s
1c270 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
1c280 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
1c290 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
1c2a0 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
1c2b0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
1c2c0 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
1c2d0 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
1c2e0 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
1c2f0 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
1c300 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
1c310 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
1c320 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
1c330 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68   string.)^.*/.ch
1c340 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
1c350 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1c360 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1c370 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
1c380 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1c390 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
1c3a0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
1c3b0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1c3c0 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  , ...);.char *sq
1c3d0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1c3e0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1c3f0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1c400 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c410 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1c420 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1c430 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1c440 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1c450 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1c460 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1c470 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1c480 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1c490 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1c4a0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1c4b0 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1c4c0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1c4d0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1c4e0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1c4f0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1c500 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1c510 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1c520 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1c530 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1c540 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1c550 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1c560 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1c570 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1c580 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1c590 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1c5a0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1c5b0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1c5c0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1c5d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1c5e0 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1c5f0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1c600 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1c610 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1c620 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1c630 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1c640 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1c650 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1c660 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1c670 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1c680 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1c690 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
1c6a0 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1c6b0 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77  c64(N) routine w
1c6c0 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a  orks just like.*
1c6d0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1c6e0 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  (N) except that 
1c6f0 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  N is an unsigned
1c700 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1c710 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1c720 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e  signed 32-bit in
1c730 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  teger..**.** ^Ca
1c740 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1c750 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1c760 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1c770 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1c780 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1c790 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1c7a0 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1c7b0 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1c7c0 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1c7d0 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1c7e0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1c7f0 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1c800 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1c810 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1c820 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1c830 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1c840 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1c850 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1c860 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1c870 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1c880 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1c890 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1c8a0 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1c8b0 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1c8c0 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1c8d0 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1c8e0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1c8f0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1c900 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1c910 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1c920 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1c930 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1c940 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1c950 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1c960 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1c970 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1c980 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1c990 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1c9a0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1c9b0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1c9c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1c9d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1c9e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1c9f0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1ca00 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1ca10 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1ca20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20  allocation X to 
1ca30 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1ca40 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
1ca50 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  X parameter to s
1ca60 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1ca70 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ,N).** is a NULL
1ca80 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1ca90 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1caa0 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1cab0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1cac0 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20  lloc(N)..** ^If 
1cad0 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
1cae0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1caf0 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20  oc(X,N) is zero 
1cb00 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1cb10 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1cb20 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1cb30 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1cb40 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1cb50 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  X)..** ^sqlite3_
1cb60 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1cb70 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1cb80 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1cb90 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1cba0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1cbb0 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1cbc0 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
1cbd0 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ory is available
1cbe0 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1cbf0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1cc00 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1cc10 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1cc20 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
1cc30 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
1cc40 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
1cc50 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1cc60 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
1cc70 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
1cc80 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74  alloc(X,N) and t
1cc90 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1cca0 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
1ccb0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
1ccc0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1ccd0 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
1cce0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74  positive, then t
1ccf0 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f  he.** prior allo
1cd00 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72  cation is not fr
1cd10 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1cd20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1cd30 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  4(X,N) interface
1cd40 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  s works the same
1cd50 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   as.** sqlite3_r
1cd60 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65  ealloc(X,N) exce
1cd70 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36  pt that N is a 6
1cd80 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  4-bit unsigned i
1cd90 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1cda0 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69  * of a 32-bit si
1cdb0 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  gned integer..**
1cdc0 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d  .** ^If X is a m
1cdd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1cde0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
1cdf0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1ce00 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  3_malloc(),.** s
1ce10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1ce20 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1ce30 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  oc(), or sqlite3
1ce40 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68  _realloc64(), th
1ce50 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
1ce60 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74  ize(X) returns t
1ce70 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20  he size of that 
1ce80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1ce90 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  n in bytes..** ^
1cea0 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1ceb0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73  ed by sqlite3_ms
1cec0 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20  ize(X) might be 
1ced0 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
1cee0 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74  number.** of byt
1cef0 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65  es requested whe
1cf00 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65  n X was allocate
1cf10 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e  d.  ^If X is a N
1cf20 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1cf30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1cf40 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72  e(X) returns zer
1cf50 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20  o.  If X points 
1cf60 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61  to something tha
1cf70 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20  t is not.** the 
1cf80 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d  beginning of mem
1cf90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
1cfa0 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20  or if it points 
1cfb0 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a  to a formerly.**
1cfc0 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c   valid memory al
1cfd0 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61  location that ha
1cfe0 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64  s now been freed
1cff0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
1d000 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ior.** of sqlite
1d010 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e  3_msize(X) is un
1d020 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73  defined and poss
1d030 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ibly harmful..**
1d040 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1d050 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1d060 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71  te3_malloc(), sq
1d070 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1d080 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1d090 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69  oc64(), and sqli
1d0a0 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a  te3_realloc64().
1d0b0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1d0c0 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1d0d0 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1d0e0 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1d0f0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1d100 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1d110 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1d120 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1d130 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1d140 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1d150 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1d160 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1d170 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1d180 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1d190 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1d1a0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1d1b0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1d1c0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1d1d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1d1e0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1d1f0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1d200 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1d210 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1d220 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1d230 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1d240 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1d250 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1d260 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1d270 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1d280 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1d290 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1d2a0 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1d2b0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1d2c0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1d2d0 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1d2e0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1d2f0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1d300 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1d310 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1d320 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1d330 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1d340 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1d350 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1d360 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1d370 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1d380 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1d390 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1d3a0 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1d3b0 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1d3c0 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1d3d0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1d3e0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1d3f0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1d400 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1d410 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1d420 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1d430 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d440 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1d450 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1d460 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1d470 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1d480 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1d490 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1d4a0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1d4b0 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1d4c0 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1d4d0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1d4e0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1d4f0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1d500 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1d510 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1d520 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1d530 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1d540 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1d550 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1d560 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1d570 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
1d580 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1d590 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
1d5a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73  lite3_malloc64(s
1d5b0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
1d5c0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1d5d0 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
1d5e0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1d5f0 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a  _realloc64(void*
1d600 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
1d610 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1d620 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c  free(void*);.sql
1d630 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69  ite3_uint64 sqli
1d640 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29  te3_msize(void*)
1d650 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d660 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1d670 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
1d680 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
1d690 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
1d6a0 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
1d6b0 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
1d6c0 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
1d6d0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1d6e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
1d6f0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
1d700 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1d710 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
1d720 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
1d730 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1d740 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
1d750 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
1d760 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1d770 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1d780 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1d790 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
1d7a0 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
1d7b0 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
1d7c0 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
1d7d0 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
1d7e0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1d7f0 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
1d800 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
1d810 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
1d820 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1d830 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
1d840 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1d850 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
1d860 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
1d870 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
1d880 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1d890 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1d8a0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1d8b0 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
1d8c0 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
1d8d0 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
1d8e0 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
1d8f0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
1d900 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
1d910 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
1d920 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
1d930 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
1d940 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
1d950 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
1d960 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1d970 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
1d980 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
1d990 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
1d9a0 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
1d9b0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
1d9c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1d9d0 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
1d9e0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
1d9f0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
1da00 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1da10 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
1da20 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
1da30 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
1da40 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1da50 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
1da60 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1da70 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
1da80 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
1da90 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1daa0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1dab0 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
1dac0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1dad0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
1dae0 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
1daf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
1db00 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
1db10 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
1db20 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
1db30 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
1db40 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
1db50 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
1db60 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
1db70 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
1db80 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
1db90 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
1dba0 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
1dbb0 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
1dbc0 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
1dbd0 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
1dbe0 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
1dbf0 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
1dc00 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
1dc10 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
1dc20 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
1dc30 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
1dc40 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
1dc50 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
1dc60 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
1dc70 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
1dc80 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
1dc90 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
1dca0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1dcb0 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
1dcc0 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
1dcd0 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
1dce0 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74  * ^The P paramet
1dcf0 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c  er can be a NULL
1dd00 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1dd10 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
1dd20 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72   has not been pr
1dd30 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20  eviously called 
1dd40 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f  or if the previo
1dd50 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e  us.** call had N
1dd60 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f   less than one o
1dd70 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
1dd80 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65   for P, then the
1dd90 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64   PRNG is.** seed
1dda0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
1ddb0 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ess obtained fro
1ddc0 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
1ddd0 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74  s method of.** t
1dde0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1ddf0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
1de00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76  .** ^If the prev
1de10 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
1de20 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e  s routine had an
1de30 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20   N of 1 or more 
1de40 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c  and a.** non-NUL
1de50 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65  L P then the pse
1de60 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
1de70 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
1de80 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
1de90 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
1dea0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
1deb0 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
1dec0 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f  ** method..*/.vo
1ded0 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
1dee0 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
1def0 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
1df00 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
1df10 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
1df20 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
1df30 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1df40 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
1df50 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1df60 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
1df70 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1df80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
1df90 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
1dfa0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
1dfb0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1dfc0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1dfd0 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
1dfe0 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
1dff0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
1e000 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e010 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1e020 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
1e030 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
1e040 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1e050 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
1e060 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1e070 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
1e080 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
1e090 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
1e0a0 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
1e0b0 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
1e0c0 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
1e0d0 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
1e0e0 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
1e0f0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1e100 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
1e110 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
1e120 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
1e130 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1e140 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
1e150 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
1e160 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
1e170 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
1e180 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
1e190 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
1e1a0 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
1e1b0 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
1e1c0 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
1e1d0 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
1e1e0 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
1e1f0 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
1e200 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
1e210 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1e220 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
1e230 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
1e240 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1e250 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1e260 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
1e270 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1e280 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
1e290 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
1e2a0 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
1e2b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
1e2c0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1e2d0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1e2e0 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
1e2f0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
1e300 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1e310 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
1e320 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
1e330 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1e340 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
1e350 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
1e360 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
1e370 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
1e380 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1e390 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
1e3a0 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
1e3b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e3c0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1e3d0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1e3e0 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
1e3f0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1e400 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1e410 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
1e420 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
1e430 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
1e440 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
1e450 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1e460 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e470 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
1e480 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
1e490 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
1e4a0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e4b0 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
1e4c0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
1e4d0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
1e4e0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1e4f0 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
1e500 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
1e510 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
1e520 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
1e530 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
1e540 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
1e550 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
1e560 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
1e570 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
1e580 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
1e590 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1e5a0 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
1e5b0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
1e5c0 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
1e5d0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1e5e0 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
1e5f0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1e600 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
1e610 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
1e620 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1e630 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1e640 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
1e650 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e660 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
1e670 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
1e680 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
1e690 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
1e6a0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
1e6b0 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
1e6c0 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
1e6d0 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
1e6e0 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
1e6f0 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
1e700 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
1e710 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
1e720 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
1e730 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
1e740 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
1e750 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
1e760 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
1e770 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1e780 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
1e790 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1e7a0 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
1e7b0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
1e7c0 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
1e7d0 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
1e7e0 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
1e7f0 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
1e800 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
1e810 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
1e820 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
1e830 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
1e840 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
1e850 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
1e860 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
1e870 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
1e880 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
1e890 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
1e8a0 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
1e8b0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1e8c0 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
1e8d0 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
1e8e0 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
1e8f0 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
1e900 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
1e910 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
1e920 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
1e930 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
1e940 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
1e950 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
1e960 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
1e970 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
1e980 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
1e990 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
1e9a0 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
1e9b0 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
1e9c0 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
1e9d0 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
1e9e0 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
1e9f0 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
1ea00 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
1ea10 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
1ea20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
1ea30 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
1ea40 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
1ea50 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
1ea60 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
1ea70 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
1ea80 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
1ea90 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
1eaa0 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
1eab0 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
1eac0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
1ead0 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
1eae0 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
1eaf0 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
1eb00 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
1eb10 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
1eb20 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
1eb30 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
1eb40 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
1eb50 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
1eb60 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
1eb70 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
1eb80 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
1eb90 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
1eba0 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
1ebb0 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
1ebc0 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
1ebd0 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
1ebe0 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
1ebf0 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
1ec00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1ec10 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
1ec20 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
1ec30 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1ec40 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
1ec50 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
1ec60 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
1ec70 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
1ec80 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
1ec90 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
1eca0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
1ecb0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1ecc0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
1ecd0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1ece0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
1ecf0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
1ed00 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
1ed10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ed20 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1ed30 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
1ed40 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
1ed50 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1ed60 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1ed70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1ed80 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1ed90 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1eda0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1edb0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1edc0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1edd0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1ede0 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
1edf0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1ee00 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
1ee10 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
1ee20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
1ee30 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
1ee40 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
1ee50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
1ee60 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
1ee70 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
1ee80 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
1ee90 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
1eea0 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
1eeb0 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
1eec0 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
1eed0 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
1eee0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1eef0 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
1ef00 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
1ef10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1ef20 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
1ef30 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
1ef40 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1ef50 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
1ef60 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
1ef70 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
1ef80 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
1ef90 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
1efa0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1efb0 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
1efc0 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
1efd0 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
1efe0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1eff0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
1f000 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1f010 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
1f020 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
1f030 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
1f040 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
1f050 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
1f060 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
1f070 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
1f080 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
1f090 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1f0a0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1f0b0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
1f0c0 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
1f0d0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1f0e0 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
1f0f0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1f100 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1f110 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1f120 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1f130 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
1f140 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
1f150 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
1f160 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
1f170 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
1f180 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
1f190 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
1f1a0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
1f1b0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
1f1c0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1f1d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1f1e0 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
1f1f0 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
1f200 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
1f210 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
1f220 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
1f230 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
1f240 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c  used as a [confl
1f250 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d  ict resolution m
1f260 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ode].** returned
1f270 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
1f280 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
1f290 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
1f2a0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
1f2b0 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
1f2c0 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
1f2d0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
1f2e0 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
1f2f0 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
1f300 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
1f310 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
1f320 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
1f330 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
1f340 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1f350 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
1f360 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1f370 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1f380 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
1f390 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
1f3a0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1f3b0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
1f3c0 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
1f3d0 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
1f3e0 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
1f3f0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1f400 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1f410 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1f420 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
1f430 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
1f440 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
1f450 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
1f460 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
1f470 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
1f480 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
1f490 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1f4a0 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
1f4b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
1f4c0 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
1f4d0 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
1f4e0 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
1f4f0 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
1f500 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
1f510 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
1f520 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
1f530 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
1f540 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
1f550 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
1f560 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
1f570 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
1f580 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
1f590 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
1f5a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
1f5b0 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
1f5c0 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
1f5d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f5e0 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
1f5f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
1f600 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
1f610 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
1f620 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
1f630 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1f640 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1f650 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
1f660 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
1f670 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
1f680 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
1f690 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
1f6a0 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
1f6b0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
1f6c0 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
1f6d0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
1f6e0 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
1f6f0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
1f700 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
1f710 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f720 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
1f730 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
1f740 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
1f750 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1f760 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
1f770 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
1f780 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1f790 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1f7a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1f7b0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
1f7c0 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
1f7d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f7e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f7f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1f800 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
1f810 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
1f820 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1f830 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1f840 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1f850 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
1f860 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
1f870 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f880 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f890 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1f8a0 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
1f8b0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
1f8c0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1f8d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f8e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1f8f0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1f900 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
1f910 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f920 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f930 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1f940 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
1f950 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1f960 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1f970 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f980 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1f990 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
1f9a0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1f9b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f9c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f9d0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
1f9e0 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
1f9f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1fa00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1fa10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1fa20 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
1fa30 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
1fa40 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1fa50 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1fa60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1fa70 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
1fa80 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
1fa90 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1faa0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1fab0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1fac0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
1fad0 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
1fae0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1faf0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1fb00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fb10 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
1fb20 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
1fb30 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1fb40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1fb50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fb60 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
1fb70 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
1fb80 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1fb90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1fba0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fbb0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
1fbc0 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
1fbd0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1fbe0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1fbf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fc00 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
1fc10 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
1fc20 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1fc30 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1fc40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1fc50 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
1fc60 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
1fc70 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1fc80 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1fc90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
1fca0 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
1fcb0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
1fcc0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1fcd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1fce0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
1fcf0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
1fd00 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
1fd10 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
1fd20 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
1fd30 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
1fd40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1fd50 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
1fd60 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
1fd70 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1fd80 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
1fd90 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1fda0 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
1fdb0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1fdc0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1fdd0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
1fde0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
1fdf0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1fe00 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1fe10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1fe20 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
1fe30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
1fe40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1fe50 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1fe60 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1fe70 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
1fe80 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
1fe90 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
1fea0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1feb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1fec0 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
1fed0 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
1fee0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1fef0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
1ff00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ff10 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
1ff20 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
1ff30 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1ff40 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1ff50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ff60 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
1ff70 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
1ff80 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1ff90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1ffa0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ffb0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
1ffc0 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
1ffd0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ffe0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1fff0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20000 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
20010 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
20020 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20030 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
20040 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20050 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
20060 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
20070 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
20080 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
20090 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
200a0 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
200b0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
200c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
200d0 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
200e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
200f0 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
20100 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
20110 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
20120 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
20130 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
20140 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
20150 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
20160 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64  onger used */.#d
20170 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43  efine SQLITE_REC
20180 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20  URSIVE          
20190 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    33   /* NULL  
201a0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
201b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a            */../*
201c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
201d0 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
201e0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
201f0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
20200 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
20210 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
20220 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
20230 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
20240 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
20250 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
20260 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
20270 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
20280 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
20290 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
202a0 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
202b0 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
202c0 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
202d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
202e0 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
202f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
20300 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20310 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
20320 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
20330 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
20340 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
20350 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
20360 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
20370 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
20380 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
20390 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
203a0 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
203b0 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
203c0 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
203d0 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
203e0 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
203f0 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
20400 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
20410 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
20420 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
20430 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
20440 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  r.)^.**.** The [
20450 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
20460 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
20470 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e  -time option can
20480 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69   be used to limi
20490 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20  t.** the length 
204a0 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
204b0 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69  ter] expansion i
204c0 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  n the output of 
204d0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e  sqlite3_trace().
204e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
204f0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
20500 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
20510 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
20520 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
20530 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
20540 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
20550 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
20560 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
20570 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
20580 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
20590 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
205a0 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
205b0 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
205c0 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
205d0 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
205e0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
205f0 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
20600 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
20610 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
20620 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
20630 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
20640 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
20650 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
20660 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
20670 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
20680 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
20690 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
206a0 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
206b0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
206c0 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
206d0 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
206e0 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
206f0 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
20700 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
20710 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
20720 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
20730 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
20740 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
20750 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
20760 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
20770 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64   SQLite..*/.void
20780 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
20790 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
207a0 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
207b0 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
207c0 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  *);.SQLITE_EXPER
207d0 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
207e0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
207f0 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
20800 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
20810 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
20820 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
20830 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
20840 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
20850 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
20860 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
20870 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
20880 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
20890 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
208a0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
208b0 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
208c0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
208d0 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
208e0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
208f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
20900 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
20910 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
20920 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
20930 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
20940 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
20950 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
20960 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
20970 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
20980 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
20990 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
209a0 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
209b0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
209c0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
209d0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
209e0 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
209f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
20a00 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
20a10 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72  er N is the appr
20a20 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f  oximate number o
20a30 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
20a40 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
20a50 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
20a60 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
20a70 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
20a80 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
20a90 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49   callback X.  ^I
20aa0 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
20ab0 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72   one then the pr
20ac0 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65  ogress.** handle
20ad0 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  r is disabled..*
20ae0 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
20af0 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
20b00 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
20b10 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
20b20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
20b30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
20b40 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
20b50 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
20b60 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
20b70 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
20b80 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
20b90 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
20ba0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
20bb0 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
20bc0 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
20bd0 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
20be0 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
20bf0 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
20c00 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
20c10 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
20c20 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
20c30 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
20c40 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
20c50 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
20c60 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
20c70 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
20c80 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
20c90 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
20ca0 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
20cb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
20cc0 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
20cd0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
20ce0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
20cf0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
20d00 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
20d10 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
20d20 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
20d30 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
20d40 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
20d50 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
20d60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
20d70 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
20d80 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
20d90 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
20da0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
20db0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
20dc0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
20dd0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
20de0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
20df0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
20e00 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
20e10 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
20e20 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
20e30 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
20e40 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
20e50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
20e60 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
20e70 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
20e80 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
20e90 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
20ea0 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
20eb0 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
20ec0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
20ed0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
20ee0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
20ef0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20f00 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
20f10 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
20f20 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
20f30 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
20f40 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
20f50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
20f60 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
20f70 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
20f80 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
20f90 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
20fa0 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
20fb0 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
20fc0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
20fd0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
20fe0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
20ff0 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
21000 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
21010 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
21020 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
21030 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
21040 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
21050 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
21060 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
21070 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
21080 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
21090 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
210a0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
210b0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
210c0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
210d0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
210e0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
210f0 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
21100 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
21110 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
21120 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
21130 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
21140 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
21150 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
21160 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
21170 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
21180 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
21190 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
211a0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
211b0 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62   encoding will b
211c0 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61  e UTF-8 for data
211d0 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73  bases created us
211e0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  ing.** sqlite3_o
211f0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
21200 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68  _open_v2().  ^Th
21210 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
21220 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  ng for databases
21230 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e  .** created usin
21240 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  g sqlite3_open16
21250 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  () will be UTF-1
21260 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
21270 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
21280 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
21290 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
212a0 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
212b0 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
212c0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
212d0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
212e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
212f0 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
21300 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
21310 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
21320 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
21330 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
21340 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
21350 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
21360 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
21370 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
21380 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
21390 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
213a0 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
213b0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
213c0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
213d0 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
213e0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
213f0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
21400 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
21410 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
21420 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
21430 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
21440 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
21450 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
21460 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
21470 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
21480 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
21490 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
214a0 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
214b0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
214c0 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
214d0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
214e0 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
214f0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
21500 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
21510 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
21520 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
21530 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
21540 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
21550 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
21560 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
21570 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
21580 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
21590 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
215a0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
215b0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
215c0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
215d0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
215e0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
215f0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
21600 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
21610 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
21620 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
21630 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
21640 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
21650 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
21660 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
21670 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
21680 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
21690 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
216a0 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
216b0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
216c0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
216d0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
216e0 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
216f0 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
21700 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
21710 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
21720 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
21730 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
21740 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
21750 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
21760 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
21770 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
21780 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
21790 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
217a0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
217b0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
217c0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
217d0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
217e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
217f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
21800 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
21810 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
21820 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
21830 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
21840 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
21850 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
21860 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
21870 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
21880 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
21890 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
218a0 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
218b0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
218c0 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
218d0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
218e0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
218f0 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
21900 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
21910 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
21920 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
21930 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
21940 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
21950 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
21960 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
21970 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
21980 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
21990 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
219a0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
219b0 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
219c0 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
219d0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
219e0 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
219f0 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
21a00 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
21a10 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
21a20 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
21a30 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
21a40 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
21a50 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
21a60 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
21a70 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
21a80 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
21a90 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
21aa0 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
21ab0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
21ac0 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
21ad0 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
21ae0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
21af0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
21b00 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
21b10 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
21b20 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
21b30 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
21b40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21b50 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
21b60 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
21b70 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
21b80 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
21b90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
21ba0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
21bb0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
21bc0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
21bd0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
21be0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
21bf0 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
21c00 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
21c10 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
21c20 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
21c30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21c40 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
21c50 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
21c60 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
21c70 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
21c80 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
21c90 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
21ca0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
21cb0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
21cc0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
21cd0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
21ce0 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
21cf0 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
21d00 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
21d10 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
21d20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
21d30 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
21d40 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
21d50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21d60 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
21d70 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
21d80 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
21d90 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
21da0 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
21db0 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
21dc0 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
21dd0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
21de0 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
21df0 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
21e00 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
21e10 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
21e20 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
21e30 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
21e40 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
21e50 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
21e60 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
21e70 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
21e80 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
21e90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
21ea0 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
21eb0 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
21ec0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
21ed0 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
21ee0 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
21ef0 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
21f00 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
21f10 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
21f20 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
21f30 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
21f40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
21f50 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
21f60 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
21f70 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
21f80 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
21f90 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
21fa0 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
21fb0 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
21fc0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
21fd0 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
21fe0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
21ff0 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
22000 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
22010 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
22020 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
22030 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
22040 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
22050 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
22060 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
22070 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
22080 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66  .** set in the f
22090 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
220a0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
220b0 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
220c0 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
220d0 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
220e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
220f0 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
22100 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
22110 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
22120 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
22130 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
22140 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
22150 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53  tion..** As of S
22160 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
22170 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d  7.7, URI filenam
22180 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
22190 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
221a0 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
221b0 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
221c0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
221d0 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
221e0 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
221f0 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
22200 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
22210 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
22220 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
22230 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
22240 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
22250 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
22260 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
22270 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
22280 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
22290 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
222a0 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
222b0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
222c0 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
222d0 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
222e0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
222f0 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
22300 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
22310 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
22320 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
22330 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
22340 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
22350 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
22360 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
22370 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
22380 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
22390 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
223a0 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
223b0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
223c0 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
223d0 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
223e0 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
223f0 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
22400 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
22410 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
22420 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
22430 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
22440 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
22450 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
22460 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
22470 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
22480 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
22490 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
224a0 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
224b0 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
224c0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
224d0 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
224e0 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c  ** ^(On windows,
224f0 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
22500 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
22510 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
22520 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
22530 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
22540 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  ).)^.**.** [[cor
22550 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
22560 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
22570 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
22580 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
22590 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
225a0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
225b0 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
225c0 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
225d0 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
225e0 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
225f0 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
22600 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75  QLite and its bu
22610 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69  ilt-in [VFSes] i
22620 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
22630 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20  following query 
22640 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
22650 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
22660 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
22670 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
22680 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
22690 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
226a0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
226b0 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
226c0 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
226d0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
226e0 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
226f0 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
22700 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
22710 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
22720 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
22730 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
22740 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
22750 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
22760 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
22770 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
22780 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
22790 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
227a0 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
227b0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
227c0 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
227d0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
227e0 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
227f0 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
22800 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
22810 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
22820 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
22830 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
22840 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
22850 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
22860 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
22870 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
22880 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
22890 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
228a0 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
228b0 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
228c0 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
228d0 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
228e0 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
228f0 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
22900 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
22910 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
22920 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
22930 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
22940 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
22950 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
22960 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
22970 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
22980 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
22990 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
229a0 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
229b0 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
229c0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
229d0 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
229e0 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
229f0 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
22a00 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
22a10 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
22a20 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
22a30 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
22a40 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
22a50 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
22a60 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
22a70 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
22a80 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
22a90 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
22aa0 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
22ab0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
22ac0 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
22ad0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
22ae0 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
22af0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
22b00 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
22b10 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
22b20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
22b30 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
22b40 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
22b50 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
22b60 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
22b70 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
22b80 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
22b90 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
22ba0 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
22bb0 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
22bc0 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
22bd0 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
22be0 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
22bf0 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
22c00 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
22c10 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
22c20 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
22c30 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
22c40 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
22c50 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
22c60 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
22c70 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
22c80 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
22c90 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
22ca0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
22cb0 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
22cc0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
22cd0 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
22ce0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
22cf0 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
22d00 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
22d10 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
22d20 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
22d30 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
22d40 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
22d50 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
22d60 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
22d70 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
22d80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
22d90 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
22da0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
22db0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
22dc0 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
22dd0 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
22de0 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
22df0 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
22e00 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
22e10 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
22e20 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
22e30 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
22e40 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
22e50 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
22e60 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
22e70 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20  HE flag..**.**  
22e80 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e  <li> <b>psow</b>
22e90 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61  : ^The psow para
22ea0 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20  meter indicates 
22eb0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
22ec0 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72  he.**     [power
22ed0 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20  safe overwrite] 
22ee0 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72  property does or
22ef0 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20   does not apply 
22f00 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74  to the.**     st
22f10 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77  orage media on w
22f20 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73  hich the databas
22f30 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a  e file resides..
22f40 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e  **.**  <li> <b>n
22f50 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20  olock</b>: ^The 
22f60 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72  nolock parameter
22f70 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
22f80 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ery parameter.**
22f90 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65       which if se
22fa0 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20  t disables file 
22fb0 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62  locking in rollb
22fc0 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65  ack journal mode
22fd0 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20  s.  This.**     
22fe0 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63  is useful for ac
22ff0 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61  cessing a databa
23000 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74  se on a filesyst
23010 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  em that does not
23020 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20  .**     support 
23030 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f  locking.  Cautio
23040 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72  n:  Database cor
23050 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ruption might re
23060 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20  sult if two.**  
23070 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65     or more proce
23080 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68  sses write to th
23090 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
230a0 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74  and any one of t
230b0 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63  hose.**     proc
230c0 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63  esses uses noloc
230d0 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  k=1..**.**  <li>
230e0 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62   <b>immutable</b
230f0 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c  >: ^The immutabl
23100 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  e parameter is a
23110 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a   boolean query.*
23120 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20  *     parameter 
23130 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74  that indicates t
23140 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
23150 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20   file is stored 
23160 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f  on.**     read-o
23170 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65  nly media.  ^Whe
23180 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73  n immutable is s
23190 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d  et, SQLite assum
231a0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20  es that the.**  
231b0 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65     database file
231c0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
231d0 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72  ed, even by a pr
231e0 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65  ocess with highe
231f0 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65  r.**     privile
23200 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64  ge, and so the d
23210 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
23220 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20  d read-only and 
23230 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20  all locking.**  
23240 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65     and change de
23250 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62  tection is disab
23260 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53  led.  Caution: S
23270 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74  etting the immut
23280 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70  able.**     prop
23290 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61  erty on a databa
232a0 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65  se file that doe
232b0 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65  s in fact change
232c0 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20   can result.**  
232d0 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20     in incorrect 
232e0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e  query results an
232f0 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52  d/or [SQLITE_COR
23300 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a  RUPT] errors..**
23310 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b       See also: [
23320 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
23330 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20  UTABLE]..**     
23340 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a    .** </ul>.**.*
23350 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
23360 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
23370 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
23380 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
23390 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
233a0 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
233b0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
233c0 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
233d0 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
233e0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
233f0 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
23400 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
23410 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
23420 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
23430 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
23440 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
23450 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
23460 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
23470 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
23480 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
23490 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
234a0 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
234b0 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
234c0 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
234d0 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
234e0 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
234f0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
23500 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
23510 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
23520 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
23530 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
23540 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
23550 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
23560 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
23570 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
23580 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
23590 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
235a0 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
235b0 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
235c0 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
235d0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
235e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
235f0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
23600 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
23610 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
23620 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
23630 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
23640 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
23650 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
23660 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
23670 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
23680 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
23690 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
236a0 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
236b0 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
236c0 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
236d0 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
236e0 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
236f0 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
23700 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
23710 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
23720 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
23730 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
23740 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
23750 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
23760 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
23770 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
23780 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
23790 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
237a0 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
237b0 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
237c0 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
237d0 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
237e0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
237f0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
23800 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
23810 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
23820 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
23830 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
23840 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
23850 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
23860 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
23870 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
23880 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
23890 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
238a0 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
238b0 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
238c0 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
238d0 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
238e0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
238f0 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
23900 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74  =unix-dotfile <t
23910 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
23920 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
23930 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
23940 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
23950 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65  FS "unix-dotfile
23960 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ".**          th
23970 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65  at uses dot-file
23980 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f  s in place of po
23990 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63  six advisory loc
239a0 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  king..** <tr><td
239b0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
239c0 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
239d0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
239e0 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
239f0 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
23a00 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
23a10 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
23a20 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
23a30 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
23a40 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
23a50 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
23a60 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
23a70 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
23a80 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
23a90 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
23aa0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
23ab0 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
23ac0 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
23ad0 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
23ae0 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
23af0 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
23b00 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
23b10 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
23b20 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
23b30 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
23b40 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
23b50 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
23b60 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
23b70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
23b80 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
23b90 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
23ba0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
23bb0 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
23bc0 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
23bd0 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
23be0 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
23bf0 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
23c00 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
23c10 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
23c20 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
23c30 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
23c40 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
23c50 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
23c60 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
23c70 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
23c80 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
23c90 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
23ca0 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
23cb0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
23cc0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
23cd0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
23ce0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
23cf0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
23d00 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
23d10 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
23d20 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
23d30 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
23d40 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
23d50 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
23d60 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
23d70 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
23d80 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
23d90 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
23da0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
23db0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
23dc0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
23dd0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
23de0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
23df0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
23e00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
23e10 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
23e20 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
23e30 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
23e40 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
23e50 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
23e60 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
23e70 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
23e80 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
23e90 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
23ea0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
23eb0 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
23ec0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
23ed0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
23ee0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
23ef0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
23f00 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
23f10 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
23f20 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
23f30 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
23f40 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
23f50 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
23f60 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
23f70 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
23f80 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
23f90 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
23fa0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
23fb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
23fc0 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
23fd0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
23fe0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
23ff0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
24000 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
24010 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
24020 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
24030 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
24040 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
24050 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
24060 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
24070 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
24080 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
24090 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
240a0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
240b0 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
240c0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
240d0 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
240e0 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
240f0 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
24100 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
24110 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
24120 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
24130 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
24140 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
24150 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
24160 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
24170 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
24180 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
24190 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
241a0 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
241b0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
241c0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
241d0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
241e0 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
241f0 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
24200 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
24210 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
24220 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
24230 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
24240 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
24250 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
24260 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
24270 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
24280 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
24290 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
242a0 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
242b0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
242c0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
242d0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
242e0 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
242f0 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
24300 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
24310 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
24320 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
24330 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
24340 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
24350 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24360 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
24370 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
24380 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
24390 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
243a0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
243b0 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
243c0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
243d0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
243e0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
243f0 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
24400 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
24410 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
24420 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
24430 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
24440 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
24450 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
24460 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
24470 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
24480 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
24490 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
244a0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
244b0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
244c0 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
244d0 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
244e0 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
244f0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
24500 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
24510 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
24520 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
24530 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
24540 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
24550 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
24560 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
24570 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
24580 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
24590 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
245a0 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
245b0 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
245c0 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
245d0 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
245e0 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
245f0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
24600 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
24610 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
24620 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
24630 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
24640 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
24650 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
24660 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
24670 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
24680 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
24690 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
246a0 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
246b0 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
246c0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
246d0 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
246e0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
246f0 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
24700 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
24710 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
24720 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
24730 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
24740 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
24750 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
24760 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
24770 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
24780 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
24790 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
247a0 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
247b0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
247c0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
247d0 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
247e0 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
247f0 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
24800 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
24810 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
24820 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
24830 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
24840 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
24850 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
24860 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
24870 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
24880 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
24890 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
248a0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
248b0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
248c0 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
248d0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
248e0 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69  char *zParam);.i
248f0 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
24900 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
24910 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
24920 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
24930 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c  t bDefault);.sql
24940 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
24950 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
24960 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
24970 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
24980 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
24990 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
249a0 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
249b0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
249c0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
249d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
249e0 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
249f0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
24a00 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
24a10 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
24a20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
24a30 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
24a40 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61   call.** associa
24a50 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
24a60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
24a70 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
24a80 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20   call failed.** 
24a90 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  but the most rec
24aa0 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
24ab0 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
24ac0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a  rn value from.**
24ad0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
24ae0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
24af0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65    ^The sqlite3_e
24b00 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
24b10 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
24b20 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
24b30 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
24b40 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
24b50 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
24b60 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
24b70 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
24b80 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
24b90 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
24ba0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
24bb0 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
24bc0 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
24bd0 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
24be0 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
24bf0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
24c00 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
24c10 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
24c20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
24c30 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
24c40 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
24c50 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
24c60 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
24c70 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
24c80 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
24c90 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
24ca0 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
24cb0 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
24cc0 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
24cd0 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
24ce0 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
24cf0 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
24d00 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
24d10 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
24d20 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
24d30 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s.)^.**.** ^The 
24d40 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29  sqlite3_errstr()
24d50 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24d60 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c  ns the English-l
24d70 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20  anguage text.** 
24d80 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
24d90 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  he [result code]
24da0 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  , as UTF-8..** ^
24db0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
24dc0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
24dd0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
24de0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a  ged internally.*
24df0 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62  * and must not b
24e00 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61  e freed by the a
24e10 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a  pplication)^..**
24e20 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
24e30 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
24e40 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
24e50 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
24e60 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
24e70 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
24e80 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
24e90 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
24ea0 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
24eb0 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
24ec0 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
24ed0 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
24ee0 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
24ef0 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
24f00 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
24f10 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
24f20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
24f30 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
24f40 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
24f50 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
24f60 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
24f70 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
24f80 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
24f90 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
24fa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24fb0 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
24fc0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
24fd0 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
24fe0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
24ff0 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
25000 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
25010 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
25020 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
25030 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
25040 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
25050 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
25060 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
25070 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
25080 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
25090 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
250a0 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
250b0 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
250c0 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
250d0 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
250e0 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
250f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
25100 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
25110 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
25120 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
25130 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
25140 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
25150 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
25160 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
25170 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
25180 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
25190 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
251a0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
251b0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
251c0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
251d0 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
251e0 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  *);.const char *
251f0 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69  sqlite3_errstr(i
25200 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
25210 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d  3REF: SQL Statem
25220 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
25230 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
25240 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
25250 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25260 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
25270 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
25280 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
25290 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
252a0 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  ement..** This o
252b0 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73  bject is various
252c0 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70  ly known as a "p
252d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
252e0 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70  t" or a.** "comp
252f0 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
25300 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73  nt" or simply as
25310 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a   a "statement"..
25320 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f  **.** The life o
25330 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  f a statement ob
25340 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68  ject goes someth
25350 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ing like this:.*
25360 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
25370 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a  > Create the obj
25380 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
25390 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
253a0 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a   or a related.**
253b0 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a        function..
253c0 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c  ** <li> Bind val
253d0 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72  ues to [host par
253e0 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
253f0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
25400 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
25410 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
25420 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
25430 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
25440 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
25450 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
25460 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61  i> Reset the sta
25470 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
25480 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
25490 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
254a0 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
254b0 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
254c0 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
254d0 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
254e0 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
254f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
25500 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  ]..** </ol>.**.*
25510 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d  * Refer to docum
25520 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  entation on indi
25530 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61  vidual methods a
25540 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f  bove for additio
25550 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
25560 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
25570 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
25580 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
25590 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
255a0 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
255b0 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  s.**.** ^(This i
255c0 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
255d0 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
255e0 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
255f0 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
25600 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
25610 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
25620 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
25630 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
25640 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
25650 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
25660 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
25670 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
25680 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
25690 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
256a0 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
256b0 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
256c0 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
256d0 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
256e0 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
256f0 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
25700 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
25710 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
25720 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
25730 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
25740 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
25750 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
25760 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
25770 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
25780 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
25790 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
257a0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
257b0 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
257c0 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
257d0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
257e0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
257f0 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
25800 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
25810 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
25820 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
25830 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
25840 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
25850 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
25860 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
25870 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
25880 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
25890 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
258a0 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
258b0 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
258c0 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
258d0 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
258e0 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
258f0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
25900 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
25910 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
25920 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
25930 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
25940 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
25950 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
25960 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
25970 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
25980 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
25990 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
259a0 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
259b0 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
259c0 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
259d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
259e0 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
259f0 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
25a00 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
25a10 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
25a20 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
25a30 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
25a40 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
25a50 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
25a60 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
25a70 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
25a80 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
25a90 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
25aa0 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
25ab0 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
25ac0 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
25ad0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
25ae0 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
25af0 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
25b00 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
25b10 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
25b20 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
25b30 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
25b40 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
25b50 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
25b60 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
25b70 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
25b80 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
25b90 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
25ba0 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
25bb0 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
25bc0 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
25bd0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
25be0 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
25bf0 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
25c00 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
25c10 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
25c20 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
25c30 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
25c40 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
25c50 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
25c60 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
25c70 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
25c80 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
25c90 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
25ca0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
25cb0 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
25cc0 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
25cd0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
25ce0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
25cf0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
25d00 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
25d10 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
25d20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
25d30 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
25d40 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69  e releases..*/.i
25d50 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
25d60 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
25d70 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
25d80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25d90 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
25da0 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
25db0 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
25dc0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
25dd0 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
25de0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
25df0 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
25e00 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
25e10 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
25e20 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
25e30 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
25e40 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
25e50 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
25e60 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
25e70 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
25e80 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
25e90 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
25ea0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
25eb0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
25ec0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
25ed0 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
25ee0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
25ef0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
25f00 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
25f10 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
25f20 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25f30 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
25f40 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
25f50 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
25f60 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
25f70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25f80 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
25f90 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25fa0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
25fb0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25fc0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
25fd0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
25fe0 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
25ff0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
26000 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
26010 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26020 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
26030 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26040 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
26050 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
26060 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
26070 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
26080 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
26090 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
260a0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
260b0 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
260c0 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
260d0 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
260e0 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
260f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26100 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
26110 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26120 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
26130 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26140 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
26150 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
26160 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
26170 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
26180 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
26190 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
261a0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
261b0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
261c0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
261d0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
261e0 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
261f0 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
26200 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
26210 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26220 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
26230 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26240 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
26250 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26260 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
26270 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
26280 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
26290 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
262a0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
262b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
262c0 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
262d0 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
262e0 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
262f0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
26300 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
26310 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
26320 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
26330 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26340 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
26350 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
26360 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
26370 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
26380 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
26390 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
263a0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
263b0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
263c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
263d0 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
263e0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
263f0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
26400 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
26410 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
26420 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
26430 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
26440 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
26450 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
26460 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
26470 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
26480 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
26490 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
264a0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
264b0 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
264c0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
264d0 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
264e0 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
264f0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
26500 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
26510 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
26520 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26530 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
26540 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26550 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
26560 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
26570 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
26580 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
26590 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
265a0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
265b0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
265c0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
265d0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
265e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
265f0 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
26600 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
26610 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
26620 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
26630 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74  _THREADS]] ^(<dt
26640 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  >SQLITE_LIMIT_WO
26650 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74  RKER_THREADS</dt
26660 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26670 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
26680 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20  uxiliary worker 
26690 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73  threads that a s
266a0 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72  ingle.** [prepar
266b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61  ed statement] ma
266c0 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a  y start.</dd>)^.
266d0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
266e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
266f0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
26700 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
26710 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26720 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
26730 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
26740 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26750 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
26760 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
26770 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26780 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
26790 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
267a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
267b0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
267c0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
267d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
267e0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
267f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26800 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
26810 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
26820 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
26830 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
26840 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
26850 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26860 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
26870 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
26880 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
26890 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
268a0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
268b0 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
268c0 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
268d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
268e0 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
268f0 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
26900 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
26910 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20  ER_THREADS      
26920 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43       11../*.** C
26930 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
26940 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
26950 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
26960 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
26970 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
26980 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
26990 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
269a0 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
269b0 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
269c0 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
269d0 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
269e0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
269f0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
26a00 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
26a10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
26a20 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
26a30 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
26a40 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
26a50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
26a60 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
26a70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
26a80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
26a90 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
26aa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
26ab0 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
26ac0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
26ad0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
26ae0 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
26af0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
26b00 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
26b10 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
26b20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
26b30 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
26b40 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
26b50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
26b60 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
26b70 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
26b80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
26b90 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
26ba0 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
26bb0 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
26bc0 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
26bd0 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
26be0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
26bf0 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
26c00 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
26c10 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
26c20 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e  . ^If nByte is n
26c30 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
26c40 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
26c50 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
26c60 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
26c70 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e  m zSql.  ^When n
26c80 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
26c90 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
26ca0 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
26cb0 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
26cc0 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
26cd0 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
26ce0 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
26cf0 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
26d00 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
26d10 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
26d20 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
26d30 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
26d40 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
26d50 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
26d60 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
26d70 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
26d80 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
26d90 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
26da0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
26db0 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
26dc0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
26dd0 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
26de0 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
26df0 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
26e00 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
26e10 79 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76  ytes as this sav
26e20 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68  es SQLite from h
26e30 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65  aving to.** make
26e40 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69   a copy of the i
26e50 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  nput string..**.
26e60 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
26e70 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
26e80 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
26e90 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
26ea0 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
26eb0 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
26ec0 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
26ed0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
26ee0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
26ef0 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
26f00 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
26f10 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
26f20 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
26f30 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
26f40 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
26f50 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
26f60 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
26f70 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
26f80 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
26f90 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
26fa0 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
26fb0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
26fc0 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
26fd0 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
26fe0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
26ff0 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
27000 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
27010 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
27020 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
27030 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
27040 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
27050 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
27060 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
27070 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
27080 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
27090 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
270a0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
270b0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
270c0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
270d0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
270e0 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
270f0 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
27100 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
27110 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
27120 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
27130 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
27140 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
27150 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
27160 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
27170 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
27180 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
27190 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
271a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
271b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
271c0 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
271d0 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
271e0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
271f0 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
27200 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
27210 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
27220 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
27230 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
27240 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
27250 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
27260 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
27270 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
27280 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
27290 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
272a0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
272b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
272c0 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
272d0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
272e0 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
272f0 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
27300 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
27310 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
27320 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
27330 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
27340 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
27350 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
27360 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
27370 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
27380 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
27390 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
273a0 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
273b0 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
273c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
273d0 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
273e0 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
273f0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
27400 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
27410 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e  it again. As man
27420 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58  y as [SQLITE_MAX
27430 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a  _SCHEMA_RETRY].*
27440 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f  * retries will o
27450 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69  ccur before sqli
27460 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73  te3_step() gives
27470 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20   up and returns 
27480 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c  an error..** </l
27490 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
274a0 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
274b0 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
274c0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
274d0 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
274e0 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
274f0 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
27500 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
27510 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
27520 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
27530 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
27540 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
27550 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
27560 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
27570 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
27580 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
27590 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
275a0 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
275b0 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
275c0 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
275d0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
275e0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
275f0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
27600 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
27610 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
27620 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
27630 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
27640 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
27650 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
27660 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
27670 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
27680 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
27690 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
276a0 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
276b0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
276c0 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
276d0 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
276e0 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
276f0 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
27700 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
27710 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
27720 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
27730 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
27740 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
27750 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
27760 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
27770 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
27780 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
27790 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
277a0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
277b0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
277c0 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
277d0 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
277e0 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
277f0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
27800 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
27810 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
27820 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
27830 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
27840 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
27850 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
27860 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
27870 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
27880 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
27890 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
278a0 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
278b0 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
278c0 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
278d0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
278e0 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT3] compile-ti
278f0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
27900 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  bled..** </li>.*
27910 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ol>.*/.int s
27920 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
27930 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
27940 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
27950 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
27960 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
27970 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
27980 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
27990 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
279a0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
279b0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
279c0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
279d0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
279e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
279f0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
27a00 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
27a10 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
27a20 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
27a30 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
27a40 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
27a50 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
27a60 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
27a70 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
27a80 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
27a90 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
27aa0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
27ab0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
27ac0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
27ad0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
27ae0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
27af0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
27b00 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
27b10 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
27b20 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
27b30 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
27b40 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
27b50 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
27b60 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
27b70 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
27b80 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
27b90 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
27ba0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
27bb0 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
27bc0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
27bd0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
27be0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
27bf0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
27c00 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
27c10 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
27c20 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
27c30 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
27c40 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
27c50 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
27c60 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
27c70 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
27c80 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
27c90 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
27ca0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
27cb0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
27cc0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
27cd0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
27ce0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
27cf0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
27d00 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
27d10 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
27d20 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
27d30 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
27d40 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
27d50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
27d60 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
27d70 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
27d80 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
27d90 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
27da0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
27db0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
27dc0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
27dd0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
27de0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
27df0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
27e00 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
27e10 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
27e20 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
27e30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27e40 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
27e50 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a  tatement SQL.**.
27e60 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
27e70 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
27e80 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
27e90 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
27ea0 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
27eb0 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
27ec0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
27ed0 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
27ee0 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
27ef0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
27f00 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
27f10 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
27f20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
27f30 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  are16_v2()]..*/.
27f40 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
27f50 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
27f60 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
27f70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
27f80 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
27f90 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69  QL Statement Wri
27fa0 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65  tes The Database
27fb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27fc0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
27fd0 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
27fe0 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
27ff0 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
28000 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
28010 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28020 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
28030 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
28040 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
28050 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
28060 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
28070 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
28080 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
28090 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
280a0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
280b0 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
280c0 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
280d0 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
280e0 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
280f0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
28100 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
28110 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
28120 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
28130 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
28140 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
28150 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
28160 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
28170 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
28180 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
28190 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
281a0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
281b0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
281c0 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
281d0 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
281e0 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
281f0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
28200 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
28210 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
28220 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
28230 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
28240 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
28250 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
28260 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
28270 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
28280 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
28290 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
282a0 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
282b0 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
282c0 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
282d0 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
282e0 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
282f0 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
28300 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
28310 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
28320 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
28330 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
28340 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
28350 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
28360 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
28370 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
28380 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
28390 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
283a0 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
283b0 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
283c0 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
283d0 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
283e0 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
283f0 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
28400 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
28410 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
28420 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
28430 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
28440 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
28450 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
28460 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
28470 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
28480 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
28490 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
284a0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
284b0 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69  es on disk..*/.i
284c0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
284d0 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
284e0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
284f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28500 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
28510 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
28520 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
28530 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28540 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
28550 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
28560 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
28570 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
28580 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28590 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
285a0 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
285b0 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
285c0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
285d0 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74  ut has not run t
285e0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64  o completion and
285f0 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  /or has not .** 
28600 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
28610 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
28620 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
28630 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
28640 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
28650 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
28660 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
28670 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
28680 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
28690 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
286a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
286b0 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
286c0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
286d0 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
286e0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
286f0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
28700 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
28710 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
28720 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
28730 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
28740 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
28750 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
28760 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
28770 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
28780 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
28790 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
287a0 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
287b0 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
287c0 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
287d0 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
287e0 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
287f0 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
28800 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
28810 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
28820 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
28830 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
28840 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71   open..*/.int sq
28850 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
28860 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
28870 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28880 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
28890 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
288a0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
288b0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
288c0 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
288d0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
288e0 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
288f0 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
28900 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
28910 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
28920 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
28930 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
28940 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
28950 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
28960 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
28970 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
28980 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
28990 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
289a0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
289b0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
289c0 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
289d0 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
289e0 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
289f0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
28a00 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28a10 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
28a20 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
28a30 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
28a40 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
28a50 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
28a60 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28a70 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
28a80 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
28a90 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
28aa0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
28ab0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
28ac0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
28ad0 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
28ae0 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
28af0 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
28b00 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
28b10 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
28b20 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
28b30 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28b40 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
28b50 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
28b60 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
28b70 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
28b80 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
28b90 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
28ba0 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
28bb0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
28bc0 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
28bd0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28be0 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
28bf0 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
28c00 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
28c10 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28c20 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
28c30 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
28c40 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
28c50 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
28c60 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
28c70 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
28c80 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
28c90 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
28ca0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
28cb0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
28cc0 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
28cd0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
28ce0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
28cf0 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
28d00 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
28d10 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
28d20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
28d30 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
28d40 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
28d50 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
28d60 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
28d70 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
28d80 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
28d90 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
28da0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
28db0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
28dc0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
28dd0 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
28de0 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
28df0 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
28e00 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
28e10 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
28e20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
28e30 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
28e40 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
28e50 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
28e60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
28e70 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
28e80 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
28e90 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
28ea0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
28eb0 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
28ec0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
28ed0 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
28ee0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
28ef0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
28f00 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
28f10 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
28f20 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
28f30 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
28f40 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
28f50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28f60 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
28f70 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
28f80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
28f90 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
28fa0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
28fb0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
28fc0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
28fd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
28fe0 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
28ff0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
29000 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
29010 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29020 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
29030 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
29040 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
29050 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
29060 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
29070 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
29080 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
29090 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
290a0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
290b0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
290c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
290d0 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
290e0 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
290f0 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
29100 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
29110 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
29120 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
29130 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
29140 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
29150 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29160 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
29170 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
29180 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
29190 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
291a0 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
291b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
291c0 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
291d0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
291e0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
291f0 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
29200 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
29210 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
29220 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
29230 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
29240 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
29250 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
29260 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
29270 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
29280 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
29290 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
292a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
292b0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
292c0 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
292d0 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
292e0 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
292f0 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
29300 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
29310 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
29320 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
29330 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
29340 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
29350 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
29360 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
29370 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
29380 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
29390 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
293a0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
293b0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
293c0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
293d0 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
293e0 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
293f0 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
29400 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
29410 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
29420 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
29430 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
29440 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
29450 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
29460 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
29470 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
29480 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
29490 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
294a0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
294b0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
294c0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
294d0 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
294e0 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
294f0 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
29500 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
29510 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
29520 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
29530 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
29540 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
29550 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
29560 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
29570 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
29580 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
29590 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
295a0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
295b0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
295c0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
295d0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
295e0 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
295f0 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
29600 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
29610 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
29620 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
29630 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
29640 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
29650 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
29660 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
29670 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
29680 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
29690 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
296a0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
296b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
296c0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
296d0 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
296e0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
296f0 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
29700 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
29710 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
29720 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
29730 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
29740 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
29750 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
29760 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
29770 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29780 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
29790 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
297a0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
297b0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
297c0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
297d0 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
297e0 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
297f0 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
29800 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
29810 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
29820 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
29830 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
29840 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
29850 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
29860 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
29870 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
29880 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
29890 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
298a0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
298b0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
298c0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
298d0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
298e0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
298f0 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
29900 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
29910 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
29920 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
29930 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
29940 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
29950 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
29960 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
29970 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
29980 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
29990 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
299a0 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
299b0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
299c0 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
299d0 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
299e0 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
299f0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
29a00 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
29a10 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
29a20 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
29a30 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
29a40 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
29a50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
29a60 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
29a70 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
29a80 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
29a90 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
29aa0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
29ab0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
29ac0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
29ad0 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
29ae0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
29af0 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
29b00 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
29b10 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
29b20 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
29b30 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
29b40 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
29b50 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
29b60 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
29b70 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
29b80 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
29b90 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
29ba0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
29bb0 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71  d_text16() or sq
29bc0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
29bd0 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74  4() then.** that
29be0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
29bf0 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
29c00 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
29c10 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
29c20 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
29c30 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
29c40 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
29c50 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
29c60 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
29c70 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
29c80 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
29c90 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
29ca0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
29cb0 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
29cc0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
29cd0 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
29ce0 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
29cf0 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
29d00 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
29d10 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
29d20 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
29d30 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
29d40 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
29d50 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
29d60 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74   the BLOB and st
29d70 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74  ring binding int
29d80 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20  erfaces.** is a 
29d90 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
29da0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
29db0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
29dc0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
29dd0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
29de0 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
29df0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
29e00 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
29e10 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
29e20 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
29e30 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41  e call to bind A
29e40 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66  PI fails..** ^If
29e50 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
29e60 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
29e70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
29e80 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
29e90 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
29ea0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
29eb0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
29ec0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
29ed0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
29ee0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
29ef0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
29f00 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
29f10 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
29f20 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
29f30 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
29f40 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
29f50 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
29f60 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
29f70 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
29f80 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
29f90 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
29fa0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
29fb0 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
29fc0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
29fd0 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
29fe0 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
29ff0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
2a000 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
2a010 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
2a020 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
2a030 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
2a040 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
2a050 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
2a060 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
2a070 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
2a080 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2a090 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2a0a0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
2a0b0 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
2a0c0 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
2a0d0 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
2a0e0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
2a0f0 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
2a100 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
2a110 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
2a120 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
2a130 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
2a140 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
2a150 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a160 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2a170 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
2a180 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
2a190 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
2a1a0 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
2a1b0 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
2a1c0 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
2a1d0 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
2a1e0 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
2a1f0 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
2a200 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
2a210 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
2a220 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
2a230 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
2a240 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
2a250 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
2a260 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
2a270 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
2a280 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2a290 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
2a2a0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
2a2b0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
2a2c0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
2a2d0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
2a2e0 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
2a2f0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2a300 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
2a310 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
2a320 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2a330 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
2a340 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
2a350 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
2a360 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a370 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
2a380 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
2a390 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
2a3a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2a3b0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
2a3c0 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
2a3d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2a3e0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
2a3f0 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
2a400 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2a410 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
2a420 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
2a430 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
2a440 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a450 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
2a460 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
2a470 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
2a480 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
2a490 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
2a4a0 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
2a4b0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
2a4c0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
2a4d0 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
2a4e0 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
2a4f0 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
2a500 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
2a510 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a520 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
2a530 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2a540 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
2a550 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
2a560 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
2a570 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
2a580 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42  ** ^[SQLITE_TOOB
2a590 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  IG] might be ret
2a5a0 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a  urned if the siz
2a5b0 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72  e of a string or
2a5c0 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73   BLOB.** exceeds
2a5d0 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20   limits imposed 
2a5e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
2a5f0 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
2a600 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20  _LENGTH]) or.** 
2a610 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47  [SQLITE_MAX_LENG
2a620 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  TH]..** ^[SQLITE
2a630 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
2a640 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
2a650 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
2a660 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
2a670 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
2a680 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
2a690 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
2a6a0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2a6b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a6c0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2a6d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2a6e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2a6f0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2a700 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a710 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
2a720 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
2a730 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2a740 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2a750 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
2a760 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2a770 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2a780 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
2a790 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2a7a0 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  oid*, sqlite3_ui
2a7b0 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2a7c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2a7d0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2a7e0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2a7f0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2a800 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
2a810 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
2a820 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
2a830 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
2a840 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2a850 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
2a860 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
2a870 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
2a880 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
2a890 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
2a8a0 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
2a8b0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
2a8c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2a8d0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74  ,const char*,int
2a8e0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2a8f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2a900 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
2a910 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2a920 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2a930 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2a940 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2a950 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33  d_text64(sqlite3
2a960 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2a970 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
2a980 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2a990 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a9a0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2a9b0 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  ), unsigned char
2a9c0 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20   encoding);.int 
2a9d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2a9e0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2a9f0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
2aa00 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2aa10 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
2aa20 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2aa30 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
2aa40 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
2aa50 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
2aa60 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
2aa70 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
2aa80 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2aa90 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
2aaa0 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
2aab0 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
2aac0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2aad0 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
2aae0 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
2aaf0 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
2ab00 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
2ab10 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
2ab20 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
2ab30 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
2ab40 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
2ab50 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
2ab60 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
2ab70 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
2ab80 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
2ab90 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
2aba0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
2abb0 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
2abc0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
2abd0 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
2abe0 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
2abf0 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
2ac00 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
2ac10 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
2ac20 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
2ac30 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
2ac40 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
2ac50 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
2ac60 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
2ac70 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
2ac80 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
2ac90 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
2aca0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2acb0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2acc0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2acd0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2ace0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2acf0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2ad00 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2ad10 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2ad20 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2ad30 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
2ad40 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2ad50 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
2ad60 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
2ad70 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eter.**.** ^The 
2ad80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2ad90 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
2ada0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2adb0 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
2adc0 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
2add0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
2ade0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2adf0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
2ae00 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
2ae10 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
2ae20 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2ae30 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2ae40 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
2ae50 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
2ae60 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
2ae70 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2ae80 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
2ae90 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
2aea0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
2aeb0 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
2aec0 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
2aed0 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
2aee0 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
2aef0 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
2af00 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2af10 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
2af20 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
2af30 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
2af40 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
2af50 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
2af60 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
2af70 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
2af80 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
2af90 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
2afa0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
2afb0 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
2afc0 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
2afd0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
2afe0 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
2aff0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
2b000 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
2b010 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
2b020 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2b030 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
2b040 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
2b050 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
2b060 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
2b070 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
2b080 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
2b090 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
2b0a0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
2b0b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2b0c0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2b0d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2b0e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b0f0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2b100 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2b110 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2b120 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2b130 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b140 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2b150 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2b160 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b170 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
2b180 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2b190 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b1a0 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
2b1b0 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
2b1c0 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52  en Name.**.** ^R
2b1d0 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
2b1e0 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
2b1f0 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
2b200 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
2b210 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
2b220 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
2b230 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
2b240 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
2b250 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
2b260 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2b270 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
2b280 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2b290 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
2b2a0 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
2b2b0 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
2b2c0 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
2b2d0 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
2b2e0 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
2b2f0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
2b300 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
2b310 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
2b320 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2b330 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2b340 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2b350 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2b360 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2b370 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2b380 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2b390 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2b3a0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2b3b0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2b3c0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2b3d0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b3e0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
2b3f0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
2b400 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
2b410 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2b420 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
2b430 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
2b440 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  tement.**.** ^Co
2b450 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
2b460 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
2b470 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b480 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
2b490 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
2b4a0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
2b4b0 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
2b4c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b4d0 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
2b4e0 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
2b4f0 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
2b500 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
2b510 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
2b520 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
2b530 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2b540 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2b550 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
2b560 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2b570 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2b580 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2b590 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
2b5a0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
2b5b0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2b5c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
2b5d0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
2b5e0 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
2b5f0 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
2b600 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
2b610 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
2b620 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
2b630 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
2b640 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2b650 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
2b660 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2b670 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
2b680 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2b690 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b6a0 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
2b6b0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2b6c0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2b6d0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2b6e0 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
2b6f0 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
2b700 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
2b710 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2b720 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2b730 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
2b740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2b750 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
2b760 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2b770 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2b780 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
2b790 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
2b7a0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2b7b0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
2b7c0 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
2b7d0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
2b7e0 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2b7f0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2b800 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
2b810 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2b820 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
2b830 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2b840 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
2b850 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2b860 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
2b870 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
2b880 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
2b890 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
2b8a0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2b8b0 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
2b8c0 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
2b8d0 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
2b8e0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
2b8f0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
2b900 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2b910 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2b920 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2b930 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2b940 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2b950 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2b960 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2b970 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2b980 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2b990 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
2b9a0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
2b9b0 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
2b9c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2b9d0 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
2b9e0 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
2b9f0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
2ba00 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
2ba10 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
2ba20 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
2ba30 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
2ba40 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
2ba50 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
2ba60 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
2ba70 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
2ba80 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2ba90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2baa0 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
2bab0 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
2bac0 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
2bad0 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
2bae0 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
2baf0 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
2bb00 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
2bb10 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
2bb20 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
2bb30 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
2bb40 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
2bb50 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
2bb60 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
2bb70 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
2bb80 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  xt..*/.const cha
2bb90 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2bba0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2bbb0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
2bbc0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2bbd0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2bbe0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2bbf0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
2bc00 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
2bc10 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
2bc20 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
2bc30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
2bc40 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
2bc50 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
2bc60 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2bc70 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
2bc80 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
2bc90 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
2bca0 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
2bcb0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
2bcc0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
2bcd0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2bce0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
2bcf0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
2bd00 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
2bd10 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
2bd20 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
2bd30 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
2bd40 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
2bd50 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
2bd60 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
2bd70 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
2bd80 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
2bd90 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
2bda0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
2bdb0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2bdc0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
2bdd0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2bde0 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
2bdf0 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
2be00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
2be10 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
2be20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2be30 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2be40 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2be50 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2be60 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2be70 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2be80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2be90 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2bea0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2beb0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
2bec0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
2bed0 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
2bee0 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
2bef0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
2bf00 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
2bf10 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
2bf20 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
2bf30 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
2bf40 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2bf50 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
2bf60 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2bf70 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
2bf80 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
2bf90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2bfa0 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
2bfb0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2bfc0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2bfd0 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
2bfe0 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
2bff0 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
2c000 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
2c010 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2c020 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2c030 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
2c040 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
2c050 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
2c060 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
2c070 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2c080 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
2c090 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2c0a0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
2c0b0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
2c0c0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
2c0d0 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
2c0e0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2c0f0 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
2c100 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
2c110 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
2c120 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
2c130 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2c140 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
2c150 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
2c160 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
2c170 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
2c180 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
2c190 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
2c1a0 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
2c1b0 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
2c1c0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
2c1d0 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
2c1e0 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
2c1f0 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
2c200 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
2c210 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
2c220 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
2c230 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
2c240 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
2c250 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
2c260 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
2c270 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
2c280 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
2c290 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2c2a0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
2c2b0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
2c2c0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
2c2d0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
2c2e0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2c2f0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2c300 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
2c310 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2c320 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
2c330 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
2c340 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
2c350 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
2c360 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2c370 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
2c380 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
2c390 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2c3a0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2c3b0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
2c3c0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2c3d0 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
2c3e0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
2c3f0 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
2c400 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
2c410 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
2c420 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
2c430 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2c440 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2c450 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2c460 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2c470 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2c480 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
2c490 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2c4a0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2c4b0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2c4c0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
2c4d0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2c4e0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2c4f0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
2c500 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2c510 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2c520 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2c530 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
2c540 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2c550 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
2c560 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
2c570 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
2c580 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2c590 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2c5a0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2c5b0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2c5c0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2c5d0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
2c5e0 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
2c5f0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2c600 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
2c610 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
2c620 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c630 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
2c640 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
2c650 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2c660 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
2c670 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
2c680 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
2c690 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
2c6a0 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
2c6b0 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
2c6c0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2c6d0 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
2c6e0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2c6f0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
2c700 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
2c710 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
2c720 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2c730 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
2c740 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2c750 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
2c760 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
2c770 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2c780 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2c790 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
2c7a0 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
2c7b0 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
2c7c0 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
2c7d0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
2c7e0 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
2c7f0 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
2c800 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
2c810 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
2c820 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
2c830 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
2c840 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
2c850 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
2c860 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
2c870 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
2c880 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
2c890 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
2c8a0 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
2c8b0 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
2c8c0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
2c8d0 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
2c8e0 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
2c8f0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
2c900 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
2c910 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
2c920 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
2c930 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
2c940 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
2c950 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
2c960 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
2c970 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
2c980 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
2c990 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
2c9a0 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
2c9b0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
2c9c0 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
2c9d0 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
2c9e0 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
2c9f0 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
2ca00 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
2ca10 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
2ca20 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
2ca30 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
2ca40 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
2ca50 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  values..*/.const
2ca60 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2ca70 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
2ca80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2ca90 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2caa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2cab0 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
2cac0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2cad0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
2cae0 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
2caf0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66  atement.**.** Af
2cb00 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
2cb10 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
2cb20 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
2cb30 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
2cb40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2cb50 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2cb60 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2cb70 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
2cb80 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2cb90 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
2cba0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
2cbb0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
2cbc0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2cbd0 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
2cbe0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
2cbf0 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
2cc00 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
2cc10 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
2cc20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
2cc30 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
2cc40 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
2cc50 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
2cc60 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
2cc70 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
2cc80 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
2cc90 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
2cca0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2ccb0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2ccc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2ccd0 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
2cce0 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
2ccf0 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
2cd00 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2cd10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2cd20 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
2cd30 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
2cd40 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2cd50 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
2cd60 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2cd70 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
2cd80 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
2cd90 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
2cda0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
2cdb0 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
2cdc0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
2cdd0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
2cde0 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
2cdf0 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
2ce00 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
2ce10 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
2ce20 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
2ce30 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
2ce40 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
2ce50 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
2ce60 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
2ce70 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
2ce80 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
2ce90 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
2cea0 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
2ceb0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
2cec0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
2ced0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
2cee0 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
2cef0 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
2cf00 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
2cf10 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
2cf20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
2cf30 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2cf40 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
2cf50 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
2cf60 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
2cf70 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
2cf80 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
2cf90 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
2cfa0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
2cfb0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
2cfc0 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
2cfd0 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
2cfe0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2cff0 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
2d000 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
2d010 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
2d020 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
2d030 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
2d040 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
2d050 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
2d060 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
2d070 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
2d080 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
2d090 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2d0a0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2d0b0 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
2d0c0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
2d0d0 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
2d0e0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2d0f0 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
2d100 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
2d110 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
2d120 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2d130 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2d140 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
2d150 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
2d160 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
2d170 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
2d180 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2d190 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
2d1a0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
2d1b0 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
2d1c0 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
2d1d0 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
2d1e0 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
2d1f0 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
2d200 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2d210 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
2d220 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
2d230 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
2d240 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
2d250 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2d260 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
2d270 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
2d280 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
2d290 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
2d2a0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
2d2b0 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
2d2c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2d2d0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2d2e0 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
2d2f0 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
2d300 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
2d310 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
2d320 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
2d330 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
2d340 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2d350 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
2d360 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
2d370 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
2d380 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2d390 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
2d3a0 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
2d3b0 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
2d3c0 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
2d3d0 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
2d3e0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2d3f0 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
2d400 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d410 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
2d420 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
2d430 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
2d440 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
2d450 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2d460 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
2d470 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
2d480 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
2d490 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
2d4a0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
2d4b0 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
2d4c0 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
2d4d0 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
2d4e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d4f0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
2d500 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
2d510 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2d520 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
2d530 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
2d540 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
2d550 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2d560 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
2d570 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
2d580 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
2d590 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
2d5a0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2d5b0 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
2d5c0 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
2d5d0 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
2d5e0 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
2d5f0 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
2d600 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
2d610 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
2d620 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
2d630 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
2d640 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2d650 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
2d660 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
2d670 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
2d680 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
2d690 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2d6a0 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
2d6b0 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
2d6c0 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
2d6d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2d6e0 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
2d6f0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2d700 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
2d710 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2d720 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
2d730 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
2d740 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
2d750 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
2d760 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
2d770 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
2d780 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
2d790 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
2d7a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2d7b0 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
2d7c0 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
2d7d0 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
2d7e0 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
2d7f0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2d800 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
2d810 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
2d820 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
2d830 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
2d840 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
2d850 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
2d860 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
2d870 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
2d880 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
2d890 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
2d8a0 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
2d8b0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2d8c0 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
2d8d0 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
2d8e0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
2d8f0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
2d900 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
2d910 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
2d920 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2d930 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2d940 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
2d950 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
2d960 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
2d970 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
2d980 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
2d990 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
2d9a0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
2d9b0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2d9c0 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
2d9d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2d9e0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
2d9f0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
2da00 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
2da10 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
2da20 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2da30 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
2da40 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
2da50 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
2da60 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
2da70 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
2da80 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
2da90 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
2daa0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2dab0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
2dac0 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
2dad0 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
2dae0 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
2daf0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2db00 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2db10 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2db20 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
2db30 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
2db40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2db50 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2db60 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
2db70 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
2db80 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2db90 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
2dba0 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
2dbb0 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
2dbc0 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
2dbd0 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
2dbe0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2dbf0 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74  ommended..*/.int
2dc00 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
2dc10 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2dc20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2dc30 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2dc40 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
2dc50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2dc60 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2dc70 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2dc80 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2dc90 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2dca0 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20  .** current row 
2dcb0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2dcc0 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
2dcd0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2dce0 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61  ^If prepared sta
2dcf0 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f  tement P does no
2dd00 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72  t have results r
2dd10 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a  eady to return.*
2dd20 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20  * (via calls to 
2dd30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
2dd40 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  umn_int | sqlite
2dd50 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66  3_column_*()] of
2dd60 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20  .** interfaces) 
2dd70 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
2dd80 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72  a_count(P) retur
2dd90 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ns 0..** ^The sq
2dda0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2ddb0 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f  (P) routine also
2ddc0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20   returns 0 if P 
2ddd0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2dde0 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  r..** ^The sqlit
2ddf0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2de00 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2de10 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f   0 if the previo
2de20 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  us call to.** [s
2de30 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
2de40 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2de50 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71  _DONE].  ^The sq
2de60 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2de70 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  (P).** will retu
2de80 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70  rn non-zero if p
2de90 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
2dea0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
2deb0 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53  ) returned.** [S
2dec0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65  QLITE_ROW], exce
2ded0 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f  pt in the case o
2dee0 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e  f the [PRAGMA in
2def0 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d  cremental_vacuum
2df00 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c  ].** where it al
2df10 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72  ways returns zer
2df20 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65  o since each ste
2df30 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d  p of that multi-
2df40 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72  step.** pragma r
2df50 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73  eturns 0 columns
2df60 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2df70 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2df80 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2df90 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
2dfa0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
2dfb0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2dfc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2dfd0 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
2dfe0 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
2dff0 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
2e000 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
2e010 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
2e020 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
2e030 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
2e040 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
2e050 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
2e060 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2e070 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2e080 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
2e090 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
2e0a0 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
2e0b0 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
2e0c0 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
2e0d0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2e0e0 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
2e0f0 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
2e100 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
2e110 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
2e120 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
2e130 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
2e140 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
2e150 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
2e160 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
2e170 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
2e180 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
2e190 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
2e1a0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
2e1b0 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
2e1c0 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
2e1d0 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
2e1e0 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
2e1f0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2e200 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
2e210 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
2e220 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
2e230 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
2e240 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
2e250 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
2e260 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2e270 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
2e280 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
2e290 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
2e2a0 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
2e2b0 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
2e2c0 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
2e2d0 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
2e2e0 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
2e2f0 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
2e300 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
2e310 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
2e320 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  These routines f
2e330 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20  orm the "result 
2e340 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  set" interface..
2e350 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2e360 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
2e370 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
2e380 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
2e390 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
2e3a0 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
2e3b0 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
2e3c0 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
2e3d0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
2e3e0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
2e3f0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2e400 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
2e410 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
2e420 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2e430 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
2e440 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
2e450 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2e460 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
2e470 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
2e480 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
2e490 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2e4a0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
2e4b0 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
2e4c0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
2e4d0 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
2e4e0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
2e4f0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2e500 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
2e510 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
2e520 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2e530 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2e540 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
2e550 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
2e560 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2e570 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
2e580 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2e590 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
2e5a0 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
2e5b0 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
2e5c0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
2e5d0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2e5e0 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
2e5f0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2e600 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2e610 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
2e620 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
2e630 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
2e640 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2e650 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
2e660 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
2e670 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
2e680 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
2e690 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2e6a0 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
2e6b0 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
2e6c0 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
2e6d0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2e6e0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
2e6f0 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
2e700 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2e710 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2e720 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
2e730 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2e740 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
2e750 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
2e760 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
2e770 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2e780 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
2e790 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
2e7a0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2e7b0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2e7c0 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
2e7d0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
2e7e0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
2e7f0 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
2e800 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2e810 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
2e820 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2e830 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2e840 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e850 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
2e860 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2e870 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
2e880 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
2e890 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
2e8a0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
2e8b0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
2e8c0 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
2e8d0 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
2e8e0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2e8f0 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
2e900 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
2e910 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
2e920 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
2e930 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
2e940 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
2e950 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2e960 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
2e970 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
2e980 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
2e990 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
2e9a0 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
2e9b0 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
2e9c0 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
2e9d0 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
2e9e0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
2e9f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ea00 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
2ea10 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
2ea20 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
2ea30 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
2ea40 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
2ea50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2ea60 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
2ea70 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2ea80 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
2ea90 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
2eaa0 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
2eab0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
2eac0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ead0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2eae0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2eaf0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2eb00 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2eb10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2eb20 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
2eb30 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2eb40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2eb50 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
2eb60 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
2eb70 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
2eb80 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2eb90 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2eba0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2ebb0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2ebc0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2ebd0 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
2ebe0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
2ebf0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
2ec00 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
2ec10 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
2ec20 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
2ec30 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2ec40 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
2ec50 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2ec60 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
2ec70 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2ec80 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73  _bytes() returns
2ec90 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   zero..**.** ^If
2eca0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2ecb0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20   BLOB or UTF-16 
2ecc0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
2ecd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ece0 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74  ytes16().** rout
2ecf0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2ed00 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2ed10 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2ed20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2ed30 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2ed40 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65  TF-8 string, the
2ed50 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2ed60 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65  _bytes16() conve
2ed70 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
2ed80 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20  g to UTF-16 and 
2ed90 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2eda0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2edb0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2edc0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2edd0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2ede0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2edf0 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  16() uses.** [sq
2ee00 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2ee10 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
2ee20 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
2ee30 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72  -16 string and r
2ee40 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
2ee50 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2ee60 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2ee70 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2ee80 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
2ee90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2eea0 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a  es16() returns z
2eeb0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ero..**.** ^The 
2eec0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
2eed0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
2eee0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
2eef0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2ef00 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64  umn_bytes16()] d
2ef10 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  o not include th
2ef20 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
2ef30 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  rs at the end.**
2ef40 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
2ef50 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74   ^For clarity: t
2ef60 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2ef70 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2ef80 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2ef90 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
2efa0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
2efb0 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20   are the number 
2efc0 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
2efd0 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
2efe0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
2eff0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
2f000 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
2f010 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2f020 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
2f030 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f040 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
2f050 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
2f060 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  e always zero-te
2f070 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
2f080 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
2f090 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
2f0a0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
2f0b0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
2f0c0 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  B is a NULL poin
2f0d0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2f0e0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2f0f0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
2f100 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
2f110 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
2f120 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2f130 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70   object.  An unp
2f140 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2f150 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a  _value object.**
2f160 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
2f170 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
2f180 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
2f190 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
2f1a0 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
2f1b0 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
2f1c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2f1d0 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
2f1e0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2f1f0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2f200 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
2f210 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
2f220 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
2f230 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
2f240 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2f250 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
2f260 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
2f270 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
2f280 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
2f290 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2f2a0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2f2b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2f2c0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
2f2d0 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
2f2e0 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
2f2f0 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  .  ^For.** examp
2f300 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
2f310 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
2f320 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
2f330 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
2f340 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
2f350 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2f360 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
2f370 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
2f380 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
2f390 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
2f3a0 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
2f3b0 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
2f3c0 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
2f3d0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
2f3e0 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
2f3f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
2f400 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
2f410 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
2f420 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
2f430 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
2f440 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
2f450 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
2f460 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2f470 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2f480 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
2f490 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2f4a0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2f4b0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2f4c0 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
2f4d0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
2f4e0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
2f4f0 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
2f500 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
2f510 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2f520 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
2f530 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
2f540 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
2f550 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2f560 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2f570 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
2f580 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
2f590 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2f5a0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
2f5b0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
2f5c0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
2f5d0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
2f5e0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2f5f0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2f600 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
2f610 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
2f620 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2f630 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
2f640 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
2f650 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2f660 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
2f670 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2f680 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2f690 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
2f6a0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2f6b0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2f6c0 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a  [CAST] to BLOB.*
2f6d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2f6e0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2f6f0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2f700 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
2f710 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2f720 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2f730 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
2f740 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  L.** <tr><td>  T
2f750 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
2f760 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
2f770 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
2f780 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
2f790 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
2f7a0 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
2f7b0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2f7c0 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
2f7d0 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
2f7e0 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
2f7f0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2f800 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2f810 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
2f820 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
2f830 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
2f840 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
2f850 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
2f860 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
2f870 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
2f880 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
2f890 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
2f8a0 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
2f8b0 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
2f8c0 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
2f8d0 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
2f8e0 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
2f8f0 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
2f900 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
2f910 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
2f920 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
2f930 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
2f940 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
2f950 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
2f960 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
2f970 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
2f980 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
2f990 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
2f9a0 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
2f9b0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2f9c0 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
2f9d0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2f9e0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
2f9f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2fa00 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
2fa10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2fa20 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
2fa30 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
2fa40 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
2fa50 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
2fa60 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
2fa70 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
2fa80 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
2fa90 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2faa0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2fab0 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
2fac0 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
2fad0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
2fae0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2faf0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2fb00 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
2fb10 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
2fb20 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
2fb30 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
2fb40 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
2fb50 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2fb60 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2fb70 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
2fb80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2fb90 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
2fba0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2fbb0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
2fbc0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2fbd0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2fbe0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2fbf0 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
2fc00 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2fc10 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
2fc20 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
2fc30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2fc40 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2fc50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2fc60 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2fc70 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2fc80 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2fc90 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
2fca0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2fcb0 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
2fcc0 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
2fcd0 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
2fce0 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
2fcf0 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
2fd00 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
2fd10 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
2fd20 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
2fd30 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
2fd40 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
2fd50 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
2fd60 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73  inter references
2fd70 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
2fd80 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
2fd90 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
2fda0 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
2fdb0 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
2fdc0 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
2fdd0 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
2fde0 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
2fdf0 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
2fe00 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
2fe10 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
2fe20 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
2fe30 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
2fe40 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
2fe50 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
2fe60 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
2fe70 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
2fe80 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
2fe90 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
2fea0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2feb0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
2fec0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2fed0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2fee0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2fef0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2ff00 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
2ff10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ff20 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
2ff30 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2ff40 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
2ff50 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2ff60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2ff70 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
2ff80 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
2ff90 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
2ffa0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
2ffb0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
2ffc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ffd0 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
2ffe0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2fff0 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
30000 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
30010 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
30020 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
30030 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
30040 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
30050 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30060 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
30070 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
30080 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
30090 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
300a0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
300b0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
300c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
300d0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
300e0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
300f0 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
30100 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
30110 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
30120 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
30130 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
30140 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30150 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
30160 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
30170 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
30180 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
30190 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
301a0 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
301b0 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
301c0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
301d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
301e0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
301f0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
30200 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
30210 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
30220 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
30230 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
30240 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
30250 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f  ly.  Do <b>not</
30260 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  b> pass the poin
30270 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
30280 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
30290 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
302a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
302b0 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
302c0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
302d0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
302e0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
302f0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
30300 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
30310 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
30320 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
30330 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
30340 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
30350 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
30360 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
30370 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
30380 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
30390 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
303a0 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
303b0 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
303c0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
303d0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
303e0 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
303f0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
30400 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
30410 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30420 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
30430 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
30440 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
30450 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
30460 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30470 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
30480 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
30490 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
304a0 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  Col);.double sql
304b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
304c0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
304d0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
304e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
304f0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
30500 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
30510 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
30520 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
30530 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30540 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
30550 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
30560 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30570 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
30580 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
30590 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
305a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
305b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
305c0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
305d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
305e0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
305f0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
30600 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
30610 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
30620 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30630 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
30640 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
30650 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
30660 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
30670 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30680 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
30690 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
306a0 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
306b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
306c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
306d0 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
306e0 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
306f0 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
30700 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
30710 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
30720 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
30730 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
30740 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30750 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
30760 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
30770 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
30780 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
30790 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
307a0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
307b0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
307c0 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
307d0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
307e0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
307f0 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
30800 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30810 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
30820 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
30830 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
30840 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
30850 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
30860 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30870 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
30880 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
30890 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
308a0 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
308b0 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
308c0 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
308d0 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
308e0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
308f0 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
30900 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
30910 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
30920 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
30930 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
30940 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
30950 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
30960 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
30970 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
30980 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
30990 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
309a0 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
309b0 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
309c0 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
309d0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
309e0 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
309f0 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
30a00 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
30a10 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
30a20 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
30a30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
30a40 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
30a50 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
30a60 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
30a70 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
30a80 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
30a90 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
30aa0 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
30ab0 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
30ac0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
30ad0 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
30ae0 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
30af0 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
30b00 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
30b10 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
30b20 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
30b30 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
30b40 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
30b50 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
30b60 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
30b70 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
30b80 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
30b90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30ba0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
30bb0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
30bc0 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
30bd0 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
30be0 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
30bf0 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
30c00 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
30c10 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
30c20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
30c30 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
30c40 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
30c50 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
30c60 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
30c70 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
30c80 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
30c90 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
30ca0 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
30cb0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30cc0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
30cd0 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
30ce0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
30cf0 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
30d00 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
30d10 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
30d20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
30d30 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
30d40 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
30d50 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
30d60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
30d70 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
30d80 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
30d90 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
30da0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
30db0 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
30dc0 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
30dd0 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
30de0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
30df0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
30e00 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
30e10 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
30e20 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
30e30 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
30e40 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
30e50 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
30e60 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
30e70 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
30e80 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
30e90 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
30ea0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
30eb0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
30ec0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
30ed0 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
30ee0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
30ef0 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
30f00 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
30f10 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
30f20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30f30 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
30f40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
30f50 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
30f60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30f70 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
30f80 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
30f90 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
30fa0 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
30fb0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
30fc0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
30fd0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30fe0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
30ff0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
31000 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31010 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
31020 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
31030 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
31040 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
31050 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
31060 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
31070 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
31080 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
31090 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
310a0 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
310b0 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
310c0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
310d0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
310e0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
310f0 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
31100 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
31110 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
31120 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
31130 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
31140 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
31150 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
31160 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
31170 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
31180 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
31190 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
311a0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
311b0 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
311c0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
311d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
311e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
311f0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
31200 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
31210 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
31220 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
31230 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
31240 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
31250 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
31260 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
31270 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
31280 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31290 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
312a0 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
312b0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
312c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
312d0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
312e0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
312f0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
31300 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
31310 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
31320 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
31330 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
31340 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
31350 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
31360 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
31370 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
31380 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
31390 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
313a0 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
313b0 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
313c0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
313d0 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
313e0 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
313f0 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
31400 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
31410 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
31420 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
31430 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
31440 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
31450 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
31460 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
31470 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
31480 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
31490 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
314a0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
314b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
314c0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
314d0 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
314e0 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
314f0 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
31500 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
31510 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
31520 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
31530 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
31540 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
31550 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
31560 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
31570 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
31580 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
31590 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
315a0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
315b0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
315c0 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
315d0 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
315e0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
315f0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
31600 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
31610 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
31620 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
31630 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
31640 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
31650 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
31660 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
31670 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
31680 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73   should set this
31690 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
316a0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
316b0 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f  ] if the functio
316c0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
316d0 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71   invokes .** [sq
316e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
316f0 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16le()] on an in
31700 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  put, or [SQLITE_
31710 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a  UTF16BE] if the.
31720 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
31730 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74  n invokes [sqlit
31740 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
31750 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
31760 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  , or.** [SQLITE_
31770 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74  UTF16] if [sqlit
31780 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
31790 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b  )] is used, or [
317a0 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20  SQLITE_UTF8].** 
317b0 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65  otherwise.  ^The
317c0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
317d0 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
317e0 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
317f0 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66  mes using.** dif
31800 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64  ferent preferred
31810 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c   text encodings,
31820 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
31830 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
31840 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f  for.** each enco
31850 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  ding..** ^When m
31860 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
31870 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
31880 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
31890 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
318a0 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
318b0 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
318c0 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
318d0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
318e0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
318f0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
31900 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f  ameter may optio
31910 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69  nally be ORed wi
31920 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  th [SQLITE_DETER
31930 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20  MINISTIC].** to 
31940 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20  signal that the 
31950 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c  function will al
31960 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
31970 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65  same result give
31980 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e  n.** the same in
31990 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69  puts within a si
319a0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
319b0 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75  nt.  Most SQL fu
319c0 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64  nctions are.** d
319d0 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
319e0 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e  he built-in [ran
319f0 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74  dom()] SQL funct
31a00 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  ion is an exampl
31a10 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69  e of a.** functi
31a20 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64  on that is not d
31a30 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
31a40 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20  he SQLite query 
31a50 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20  planner is able 
31a60 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64  to.** perform ad
31a70 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a  ditional optimiz
31a80 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d  ations on determ
31a90 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e  inistic function
31aa0 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20  s, so use.** of 
31ab0 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  the [SQLITE_DETE
31ac0 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20  RMINISTIC] flag 
31ad0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77  is recommended w
31ae0 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  here possible..*
31af0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
31b00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
31b10 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
31b20 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
31b30 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
31b40 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
31b50 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
31b60 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
31b70 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
31b80 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
31b90 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65  ^The sixth, seve
31ba0 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70  nth and eighth p
31bb0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
31bc0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
31bd0 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
31be0 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
31bf0 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
31c00 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
31c10 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
31c20 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
31c30 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
31c40 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
31c50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
31c60 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
31c70 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
31c80 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
31c90 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
31ca0 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
31cb0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
31cc0 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
31cd0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
31ce0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
31cf0 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
31d00 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
31d10 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
31d20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
31d30 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
31d40 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
31d50 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
31d60 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
31d70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ass NULL pointer
31d80 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  s for all three 
31d90 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
31da0 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  backs..**.** ^(I
31db0 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61  f the ninth para
31dc0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
31dd0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31de0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  _v2() is not NUL
31df0 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  L,.** then it is
31e00 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
31e10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
31e20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a  data pointer. .*
31e30 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  * The destructor
31e40 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
31e50 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
31e60 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72   deleted, either
31e70 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65   by being.** ove
31e80 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20  rloaded or when 
31e90 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
31ea0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29  nection closes.)
31eb0 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75  ^.** ^The destru
31ec0 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76  ctor is also inv
31ed0 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
31ee0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
31ef0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
31f00 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57  2() fails..** ^W
31f10 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
31f20 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  or callback of t
31f30 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74  he tenth paramet
31f40 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  er is invoked, i
31f50 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61  t.** is passed a
31f60 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
31f70 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79   which is a copy
31f80 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
31f90 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69  ion data .** poi
31fa0 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
31fb0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
31fc0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
31fd0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
31fe0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ()..**.** ^It is
31ff0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
32000 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
32010 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
32020 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
32030 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
32040 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
32050 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
32060 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
32070 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
32080 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
32090 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
320a0 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
320b0 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
320c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
320d0 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
320e0 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
320f0 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
32100 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
32110 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  sed.  ^A functio
32120 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
32130 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
32140 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
32150 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
32160 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
32170 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
32180 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
32190 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
321a0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68    ^A function wh
321b0 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
321c0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
321d0 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
321e0 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
321f0 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
32200 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
32210 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
32220 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
32230 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66  erent.  .** ^A f
32240 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
32250 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
32260 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
32270 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
32280 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
32290 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
322a0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
322b0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
322c0 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
322d0 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
322e0 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69  TF16..**.** ^Bui
322f0 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
32300 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
32310 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
32320 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32330 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  ctions..**.** ^A
32340 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
32350 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
32360 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
32370 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
32380 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
32390 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
323a0 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
323b0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
323c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
323d0 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
323e0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
323f0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
32400 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
32410 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
32420 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
32430 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
32440 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
32450 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
32460 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
32470 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
32480 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
32490 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
324a0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
324b0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
324c0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
324d0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
324e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
324f0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
32500 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
32510 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
32520 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
32530 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32540 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
32550 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
32560 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e   void *zFunction
32570 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
32580 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
32590 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
325a0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
325b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
325c0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
325d0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
325e0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
325f0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
32600 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
32610 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
32620 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32630 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
32640 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
32650 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
32660 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
32670 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
32680 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
32690 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
326a0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
326b0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
326c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
326d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
326e0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
326f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32700 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
32710 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
32720 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
32730 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f  _context*),.  vo
32740 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
32750 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
32760 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
32770 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68  codings.**.** Th
32780 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
32790 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
327a0 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
327b0 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
327c0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
327d0 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
327e0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
327f0 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
32800 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50       1    /* IMP
32810 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20  : R-37514-35566 
32820 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
32830 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
32840 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d   2    /* IMP: R-
32850 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23  03371-37637 */.#
32860 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
32870 46 31 36 42 45 20 20 20 20 20 20 20 20 33 20 20  F16BE        3  
32880 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37    /* IMP: R-5197
32890 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69  1-34154 */.#defi
328a0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
328b0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
328c0 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
328d0 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
328e0 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
328f0 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
32900 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64  Deprecated */.#d
32910 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
32920 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
32930 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
32940 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
32950 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
32960 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46  3REF: Function F
32970 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lags.**.** These
32980 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62   constants may b
32990 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20  e ORed together 
329a0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
329b0 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66  LITE_UTF8 | pref
329c0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
329d0 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72  ing] as the four
329e0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  th argument.** t
329f0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
32a00 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b  e_function()], [
32a10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32a20 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  unction16()], or
32a30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
32a40 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
32a50 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
32a60 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
32a70 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a  TIC    0x800../*
32a80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
32a90 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
32aa0 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
32ab0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
32ac0 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
32ad0 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
32ae0 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
32af0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
32b00 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
32b10 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
32b20 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
32b30 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
32b40 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
32b50 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
32b60 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
32b70 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
32b80 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
32b90 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
32ba0 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
32bb0 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
32bc0 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
32bd0 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
32be0 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74   tell you what t
32bf0 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
32c00 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
32c10 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
32c20 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
32c30 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
32c40 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  e_count(sqlite3_
32c50 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
32c60 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
32c70 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
32c80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
32c90 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
32ca0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  ED int sqlite3_t
32cb0 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
32cc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
32cd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
32ce0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
32cf0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  D int sqlite3_gl
32d00 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
32d10 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
32d20 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
32d30 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
32d40 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  p(void);.SQLITE_
32d50 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
32d60 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
32d70 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64  arm(void(*)(void
32d80 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  *,sqlite3_int64,
32d90 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20  int),.          
32da0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
32db0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
32dc0 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
32dd0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
32de0 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
32df0 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
32e00 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  s.**.** The C-la
32e10 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
32e20 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
32e30 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
32e40 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
32e50 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
32e60 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
32e70 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
32e80 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
32e90 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
32ea0 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a  r aggregate..**.
32eb0 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
32ec0 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
32ed0 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
32ee0 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
32ef0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
32f00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32f10 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
32f20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32f30 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
32f40 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
32f50 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
32f60 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
32f70 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
32f80 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72  ..** The 3rd par
32f90 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
32fa0 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
32fb0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
32fc0 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
32fd0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32fe0 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
32ff0 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
33000 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
33010 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
33020 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
33030 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
33040 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
33050 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
33060 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
33070 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
33080 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
33090 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
330a0 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
330b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
330c0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
330d0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
330e0 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
330f0 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
33100 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
33110 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
33120 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
33130 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
33140 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
33150 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
33160 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
33170 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
33180 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
33190 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
331a0 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  t these routines
331b0 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
331c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
331d0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
331e0 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
331f0 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
33200 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
33210 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
33220 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
33230 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33240 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
33250 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
33260 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
33270 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
33280 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
33290 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
332a0 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
332b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
332c0 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
332d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
332e0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
332f0 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
33300 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
33310 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
33320 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
33330 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  vely..**.** ^(Th
33340 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
33350 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
33360 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
33370 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
33380 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
33390 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
333a0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
333b0 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
333c0 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
333d0 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
333e0 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
333f0 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
33400 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
33410 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
33420 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
33430 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
33440 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
33450 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
33460 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
33470 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
33480 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
33490 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
334a0 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
334b0 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
334c0 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
334d0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
334e0 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
334f0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
33500 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
33510 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
33520 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
33530 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
33540 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
33550 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
33560 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
33570 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
33580 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
33590 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
335a0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
335b0 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
335c0 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
335d0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
335e0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
335f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
33600 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
33610 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
33620 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
33630 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
33640 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
33650 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
33660 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
33670 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
33680 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
33690 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
336a0 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
336b0 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
336c0 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  eters..*/.const 
336d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
336e0 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
336f0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
33700 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
33710 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
33720 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
33730 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
33740 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f  ite3_value*);.do
33750 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
33760 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
33770 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
33780 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
33790 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
337a0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
337b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
337c0 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
337d0 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  e*);.const unsig
337e0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
337f0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
33800 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
33810 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
33820 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
33830 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33840 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
33850 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
33860 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
33870 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
33880 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
33890 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
338a0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
338b0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
338c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
338d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
338e0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
338f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33900 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33910 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
33920 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
33930 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
33940 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
33950 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
33960 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
33970 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
33980 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
33990 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
339a0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
339b0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
339c0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
339d0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
339e0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
339f0 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
33a00 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
33a10 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
33a20 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
33a30 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
33a40 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
33a50 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
33a60 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
33a70 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
33a80 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
33a90 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
33aa0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
33ab0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
33ac0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
33ad0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
33ae0 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
33af0 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
33b00 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
33b10 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
33b20 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
33b30 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
33b40 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
33b50 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
33b60 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
33b70 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
33b80 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
33b90 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
33ba0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
33bb0 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
33bc0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
33bd0 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
33be0 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
33bf0 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
33c00 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
33c10 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
33c20 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
33c30 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
33c40 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
33c50 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
33c60 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
33c70 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
33c80 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
33c90 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
33ca0 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
33cb0 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
33cc0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
33cd0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
33ce0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
33cf0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
33d00 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73  er .** when firs
33d10 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73  t called if N is
33d20 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
33d30 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
33d40 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  f a memory.** al
33d50 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
33d60 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
33d70 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
33d80 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
33d90 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33da0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
33db0 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
33dc0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
33dd0 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
33de0 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
33df0 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
33e00 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
33e10 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
33e20 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
33e30 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
33e40 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
33e50 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
33e60 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
33e70 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
33e80 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
33e90 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20  .)^  Within the 
33ea0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c  xFinal callback,
33eb0 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79   it is customary
33ec0 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69   to set.** N=0 i
33ed0 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  n calls to sqlit
33ee0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
33ef0 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61  text(C,N) so tha
33f00 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65  t no .** pointle
33f10 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ss memory alloca
33f20 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a  tions occur..**.
33f30 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
33f40 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
33f50 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
33f60 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
33f70 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
33f80 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
33f90 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
33fa0 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
33fb0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
33fc0 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
33fd0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
33fe0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
33ff0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
34000 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
34010 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
34020 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
34030 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
34040 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
34050 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
34060 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
34070 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
34080 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
34090 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
340a0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
340b0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
340c0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
340d0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
340e0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
340f0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
34100 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
34110 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
34120 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
34130 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
34140 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
34150 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34160 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
34170 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
34180 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
34190 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
341a0 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
341b0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
341c0 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
341d0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
341e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
341f0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
34200 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34210 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
34220 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
34230 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
34240 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
34250 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
34260 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
34270 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
34280 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
34290 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
342a0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
342b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
342c0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
342d0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
342e0 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
342f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
34300 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34310 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
34320 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
34330 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
34340 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
34350 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
34360 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
34370 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
34380 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
34390 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
343a0 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
343b0 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
343c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
343d0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
343e0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
343f0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
34400 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
34410 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
34420 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
34430 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
34440 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69  unction..*/.sqli
34450 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
34460 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
34470 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
34480 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34490 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
344a0 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a  liary Data.**.**
344b0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
344c0 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
344d0 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20  (non-aggregate) 
344e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  SQL functions to
344f0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65  .** associate me
34500 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75  tadata with argu
34510 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20  ment values. If 
34520 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69  the same value i
34530 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d  s passed to.** m
34540 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69  ultiple invocati
34550 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
34560 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72  SQL function dur
34570 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74  ing query execut
34580 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f  ion, under.** so
34590 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  me circumstances
345a0 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
345b0 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20  metadata may be 
345c0 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65  preserved.  An e
345d0 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65  xample.** of whe
345e0 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 65  re this might be
345f0 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20   useful is in a 
34600 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
34610 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66  on matching.** f
34620 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
34630 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
34640 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
34650 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73  ression can be s
34660 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
34670 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
34680 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72 6e  with the pattern
34690 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68   string.  .** Th
346a0 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  en as long as th
346b0 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  e pattern string
346c0 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d   remains the sam
346d0 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c  e,.** the compil
346e0 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
346f0 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
34700 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
34710 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
34720 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
34730 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
34740 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
34750 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
34760 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
34770 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
34780 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
34790 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
347a0 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
347b0 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
347c0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
347d0 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
347e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
347f0 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68  function. ^If th
34800 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61  ere is no metada
34810 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
34820 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 69   with the functi
34830 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69  on argument, thi
34840 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  s sqlite3_get_au
34850 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
34860 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e  e.** returns a N
34870 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
34880 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34890 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
348a0 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 73  P,X) interface s
348b0 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 61  aves P as metada
348c0 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a  ta for the N-th.
348d0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  ** argument of t
348e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
348f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
34900 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a    ^Subsequent.**
34910 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
34920 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_get_auxdata(C,
34930 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d  N) return P from
34940 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
34950 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
34960 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
34970 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74   call if the met
34980 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76  adata is still v
34990 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20  alid or.** NULL 
349a0 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  if the metadata 
349b0 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72 64  has been discard
349c0 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61  ed..** ^After ea
349d0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
349e0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
349f0 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20  ,N,P,X) where X 
34a00 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
34a10 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
34a20 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
34a30 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74  r function X wit
34a40 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65 78  h parameter P ex
34a50 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77  actly.** once, w
34a60 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61  hen the metadata
34a70 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a   is discarded..*
34a80 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
34a90 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65 20   to discard the 
34aa0 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79 20  metadata at any 
34ab0 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a  time, including:
34ac0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68   <ul>.** <li> wh
34ad0 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
34ae0 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
34af0 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c  rameter changes,
34b00 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e   or.** <li> when
34b10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34b20 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
34b30 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
34b40 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
34b50 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
34b60 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77  nt, or.** <li> w
34b70 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  hen sqlite3_set_
34b80 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e 76  auxdata() is inv
34b90 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  oked again on th
34ba0 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72  e same parameter
34bb0 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72  , or.** <li> dur
34bc0 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ing the original
34bd0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
34be0 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e  data() call when
34bf0 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20   a memory .**   
34c00 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72     allocation er
34c10 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c  ror occurs. </ul
34c20 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  >)^.**.** Note t
34c30 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69  he last bullet i
34c40 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54  n particular.  T
34c50 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58 20  he destructor X 
34c60 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  in .** sqlite3_s
34c70 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
34c80 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  ,X) might be cal
34c90 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  led immediately,
34ca0 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73   before the.** s
34cb0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34cc0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  ta() interface e
34cd0 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65  ven returns.  He
34ce0 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  nce sqlite3_set_
34cf0 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f  auxdata().** sho
34d00 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e 65  uld be called ne
34d10 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  ar the end of th
34d20 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
34d30 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 68  mentation and th
34d40 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d  e.** function im
34d50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
34d60 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79  uld not make any
34d70 20 75 73 65 20 6f 66 20 50 20 61 66 74 65 72 0a   use of P after.
34d80 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
34d90 75 78 64 61 74 61 28 29 20 68 61 73 20 62 65 65  uxdata() has bee
34da0 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n called..**.** 
34db0 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d  ^(In practice, m
34dc0 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65  etadata is prese
34dd0 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
34de0 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
34df0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ** function para
34e00 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
34e10 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e  compile-time con
34e20 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e  stants, includin
34e30 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  g literal.** val
34e40 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74  ues and [paramet
34e50 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73 73  ers] and express
34e60 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 72  ions composed fr
34e70 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a  om the same.)^.*
34e80 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
34e90 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
34ea0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
34eb0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
34ec0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
34ed0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
34ee0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
34ef0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
34f00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34f10 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c  int N);.void sql
34f20 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
34f30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34f40 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c  *, int N, void*,
34f50 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29   void (*)(void*)
34f60 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
34f70 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44  REF: Constants D
34f80 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20  efining Special 
34f90 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76  Destructor Behav
34fa0 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ior.**.** These 
34fb0 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  are special valu
34fc0 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  es for the destr
34fd0 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
34fe0 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
34ff0 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
35000 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
35010 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
35020 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20  t_blob()].  ^If 
35030 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
35040 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
35050 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
35060 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
35070 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
35080 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
35090 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
350a0 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
350b0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
350c0 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a  troyed.  ^The.**
350d0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
350e0 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68  T value means th
350f0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77  at the content w
35100 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67  ill likely chang
35110 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72  e in.** the near
35120 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74   future and that
35130 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d   SQLite should m
35140 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76  ake its own priv
35150 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  ate copy of.** t
35160 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72  he content befor
35170 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
35180 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69  ** The typedef i
35190 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77  s necessary to w
351a0 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c  ork around probl
351b0 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a  ems in certain.*
351c0 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e  * C++ compilers.
351d0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
351e0 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
351f0 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
35200 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
35210 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
35220 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
35230 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
35240 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
35250 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
35260 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
35270 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
35280 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
35290 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
352a0 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a  QL Function.**.*
352b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
352c0 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
352d0 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
352e0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
352f0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
35300 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
35310 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
35320 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
35330 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
35340 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
35350 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
35360 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
35370 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
35380 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
35390 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
353a0 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70  much like the [p
353b0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
353c0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66  ] family of.** f
353d0 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f  unctions used to
353e0 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   bind values to 
353f0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
35400 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74  in prepared stat
35410 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72  ements..** Refer
35420 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72   to the [SQL par
35430 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74  ameter] document
35440 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
35450 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
35460 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
35470 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
35480 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
35490 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
354a0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
354b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
354c0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
354d0 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
354e0 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
354f0 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
35500 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
35510 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
35520 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
35530 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
35540 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
35550 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35560 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74  t_zeroblob() int
35570 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20  erfaces set the 
35580 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
35590 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
355a0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
355b0 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61   be a BLOB conta
355c0 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a  ining all zero.*
355d0 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79  * bytes and N by
355e0 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65  tes in size, whe
355f0 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75  re N is the valu
35600 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72  e of the 2nd par
35610 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
35620 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35630 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72  t_double() inter
35640 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
35650 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
35660 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
35670 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
35680 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  be a floating po
35690 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66  int value specif
356a0 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e  ied.** by its 2n
356b0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
356c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
356d0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
356e0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
356f0 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74  _error16() funct
35700 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68  ions.** cause th
35710 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51  e implemented SQ
35720 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68  L function to th
35730 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
35740 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  ..** ^SQLite use
35750 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69  s the string poi
35760 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a  nted to by the.*
35770 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
35780 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  of sqlite3_resul
35790 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c  t_error() or sql
357a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
357b0 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20  r16().** as the 
357c0 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  text of an error
357d0 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69   message.  ^SQLi
357e0 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
357f0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
35800 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  ge string from s
35810 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35820 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20  ror() as UTF-8. 
35830 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72  ^SQLite.** inter
35840 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67  prets the string
35850 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
35860 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61  sult_error16() a
35870 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  s UTF-16 in nati
35880 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72  ve.** byte order
35890 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  .  ^If the third
358a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
358b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
358c0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
358d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
358e0 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20  6() is negative 
358f0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
35900 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  s as the error.*
35910 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65  * message all te
35920 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68  xt up through th
35930 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
35940 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
35950 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
35960 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
35970 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a  sult_error() or.
35980 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
35990 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
359a0 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e  on-negative then
359b0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68   SQLite takes th
359c0 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73  at many.** bytes
359d0 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
359e0 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  ) from the 2nd p
359f0 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
35a00 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
35a10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
35a20 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
35a30 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35a40 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f  _error16().** ro
35a50 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72  utines make a pr
35a60 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
35a70 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
35a80 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74  text before.** t
35a90 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e  hey return.  Hen
35aa0 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ce, the calling 
35ab0 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61  function can dea
35ac0 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f  llocate or.** mo
35ad0 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66  dify the text af
35ae0 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20  ter they return 
35af0 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
35b00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
35b10 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
35b20 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67  ) function chang
35b30 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  es the error cod
35b40 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
35b50 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73   SQLite as a res
35b60 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ult of an error 
35b70 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20  in a function.  
35b80 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20  ^By default,.** 
35b90 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69  the error code i
35ba0 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  s SQLITE_ERROR. 
35bb0 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63   ^A subsequent c
35bc0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
35bd0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
35be0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
35bf0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73  lt_error16() res
35c00 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ets the error co
35c10 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52  de to SQLITE_ERR
35c20 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  OR..**.** ^The s
35c30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35c40 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ror_toobig() int
35c50 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
35c60 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
35c70 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61  .** error indica
35c80 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
35c90 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
35ca0 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73  o long to repres
35cb0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
35cc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35cd0 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  rror_nomem() int
35ce0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
35cf0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
35d00 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61  .** error indica
35d10 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
35d20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
35d30 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  iled..**.** ^The
35d40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35d50 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
35d60 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
35d70 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
35d80 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
35d90 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
35da0 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
35db0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
35dc0 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
35dd0 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
35de0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35df0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
35e00 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
35e10 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
35e20 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
35e30 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35e40 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
35e50 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
35e60 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
35e70 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
35e80 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
35e90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
35ea0 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65  sult_null() inte
35eb0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
35ec0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
35ed0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
35ee0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35ef0 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a  on to be NULL..*
35f00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35f10 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
35f20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35f30 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c  text16(),.** sql
35f40 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35f50 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69  16le(), and sqli
35f60 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
35f70 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6be() interfaces
35f80 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75  .** set the retu
35f90 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
35fa0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
35fb0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
35fc0 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72  be.** a text str
35fd0 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70  ing which is rep
35fe0 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d  resented as UTF-
35ff0 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  8, UTF-16 native
36000 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20   byte order,.** 
36010 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e  UTF-16 little en
36020 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
36030 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70  big endian, resp
36040 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68  ectively..** ^Th
36050 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36060 5f 74 65 78 74 36 34 28 29 20 69 6e 74 65 72 66  _text64() interf
36070 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
36080 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 0a  urn value of an.
36090 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ** application-d
360a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
360b0 74 6f 20 62 65 20 61 20 74 65 78 74 20 73 74 72  to be a text str
360c0 69 6e 67 20 69 6e 20 61 6e 20 65 6e 63 6f 64 69  ing in an encodi
360d0 6e 67 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  ng.** specified 
360e0 62 79 20 74 68 65 20 66 69 66 74 68 20 28 61 6e  by the fifth (an
360f0 64 20 6c 61 73 74 29 20 70 61 72 61 6d 65 74 65  d last) paramete
36100 72 2c 20 77 68 69 63 68 20 6d 75 73 74 20 62 65  r, which must be
36110 20 6f 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49   one.** of [SQLI
36120 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
36130 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54  E_UTF16], [SQLIT
36140 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b  E_UTF16BE], or [
36150 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2e  SQLITE_UTF16LE].
36160 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65  .** ^SQLite take
36170 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
36180 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
36190 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
361a0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
361b0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
361c0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
361d0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20  erfaces..** ^If 
361e0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
361f0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
36200 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
36210 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
36220 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51  egative, then SQ
36230 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c  Lite takes resul
36240 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20  t text from the 
36250 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  2nd parameter.**
36260 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
36270 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
36280 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  r..** ^If the 3r
36290 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
362a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
362b0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
362c0 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
362d0 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
362e0 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
362f0 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
36300 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
36310 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
36320 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
36330 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
36340 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
36350 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
36360 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70  t.  If the 3rd p
36370 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
36380 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
36390 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65  t.** must be the
363a0 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74   byte offset int
363b0 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  o the string whe
363c0 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
363d0 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61  nator would.** a
363e0 70 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72  ppear if the str
363f0 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65  ing where NUL te
36400 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
36410 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
36420 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
36430 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74   string at a byt
36440 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73  e offset that is
36450 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76   less than the v
36460 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a  alue of the 3rd.
36470 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ** parameter, th
36480 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
36490 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e   string will con
364a0 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
364b0 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65  Ls and the.** re
364c0 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
364d0 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e  ons operating on
364e0 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d   strings with em
364f0 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
36500 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66  ndefined..** ^If
36510 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
36520 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
36530 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
36540 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
36550 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
36560 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
36570 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
36580 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
36590 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
365a0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
365b0 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  on the text or B
365c0 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20  LOB result when 
365d0 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
365e0 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
365f0 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
36600 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
36610 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
36620 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
36630 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73  faces or to.** s
36640 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
36650 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
36660 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
36670 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
36680 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
36690 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
366a0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
366b0 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
366c0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
366d0 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74  ** copy the cont
366e0 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d  ent of the param
366f0 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20  eter nor call a 
36700 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
36710 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65  e content.** whe
36720 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
36730 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
36740 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
36750 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
36760 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
36770 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
36780 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
36790 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
367a0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
367b0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52  nstant SQLITE_TR
367c0 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20  ANSIENT.** then 
367d0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
367e0 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c  opy of the resul
367f0 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74  t into space obt
36800 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72  ained from.** fr
36810 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
36820 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20  oc()] before it 
36830 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
36840 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36850 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
36860 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
36870 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
36880 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36890 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
368a0 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
368b0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
368c0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
368d0 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
368e0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
368f0 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  r.  ^The.** sqli
36900 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
36910 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
36920 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
36930 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
36940 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20  .** so that the 
36950 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
36960 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
36970 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
36980 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
36990 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
369a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
369b0 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
369c0 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
369d0 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73   ^A [protected s
369e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
369f0 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
36a00 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
36a10 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
36a20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
36a30 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
36a40 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
36a50 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
36a60 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
36a70 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
36a80 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
36a90 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
36aa0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
36ab0 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
36ac0 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
36ad0 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
36ae0 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
36af0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
36b00 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
36b10 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
36b20 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
36b30 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
36b40 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
36b50 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76   undefined..*/.v
36b60 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36b70 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  lt_blob(sqlite3_
36b80 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
36b90 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
36ba0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
36bb0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36bc0 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  _blob64(sqlite3_
36bd0 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74 20 76  context*,const v
36be0 6f 69 64 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  oid*,.          
36bf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36c00 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
36c10 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
36c20 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36c30 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69  sult_double(sqli
36c40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f  te3_context*, do
36c50 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69  uble);.void sqli
36c60 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36c70 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36c80 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
36c90 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
36ca0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
36cb0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
36cc0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
36cd0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
36ce0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36cf0 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f  _toobig(sqlite3_
36d00 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
36d10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36d20 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
36d30 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
36d40 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36d50 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
36d60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
36d70 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
36d80 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
36d90 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
36da0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
36db0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73  3_result_int64(s
36dc0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36dd0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
36de0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36df0 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  sult_null(sqlite
36e00 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
36e10 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36e20 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
36e30 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
36e40 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
36e50 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
36e60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
36e70 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  ext64(sqlite3_co
36e80 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
36e90 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
36ea0 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
36eb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
36ec0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75  oid(*)(void*), u
36ed0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63  nsigned char enc
36ee0 6f 64 69 6e 67 29 3b 0a 76 6f 69 64 20 73 71 6c  oding);.void sql
36ef0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36f00 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
36f10 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
36f20 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
36f30 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
36f40 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36f50 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
36f60 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
36f70 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
36f80 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
36f90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36fa0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
36fb0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
36fc0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
36fd0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
36fe0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
36ff0 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
37000 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
37010 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
37020 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
37030 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
37040 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
37050 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
37060 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
37070 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a  ing Sequences.**
37080 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
37090 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65  ions add, remove
370a0 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63  , or modify a [c
370b0 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69  ollation] associ
370c0 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ated.** with the
370d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
370e0 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
370f0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
37100 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
37110 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
37120 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54  ollation is a UT
37130 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f  F-8 string.** fo
37140 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
37150 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64  _collation() and
37160 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
37170 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a  collation_v2().*
37180 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73  * and a UTF-16 s
37190 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
371a0 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73  byte order for s
371b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
371c0 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20  llation16()..** 
371d0 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73  ^Collation names
371e0 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71   that compare eq
371f0 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  ual according to
37200 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63   [sqlite3_strnic
37210 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e  mp()] are.** con
37220 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68  sidered to be th
37230 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a  e same name..**.
37240 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61  ** ^(The third a
37250 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65  rgument (eTextRe
37260 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f  p) must be one o
37270 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a  f the constants:
37280 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
37290 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a   [SQLITE_UTF8],.
372a0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
372b0 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16LE],.** <li
372c0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  > [SQLITE_UTF16B
372d0 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
372e0 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a  ITE_UTF16], or.*
372f0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
37300 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a  TF16_ALIGNED]..*
37310 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68  * </ul>)^.** ^Th
37320 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
37330 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ent determines t
37340 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73  he encoding of s
37350 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a  trings passed.**
37360 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
37370 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
37380 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a  ack, xCallback..
37390 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
373a0 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49  UTF16] and [SQLI
373b0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
373c0 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65  ] values for eTe
373d0 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73  xtRep.** force s
373e0 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46  trings to be UTF
373f0 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62  16 with native b
37400 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54  yte order..** ^T
37410 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
37420 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20  _ALIGNED] value 
37430 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72  for eTextRep for
37440 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62  ces strings to b
37450 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76  egin.** on an ev
37460 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e  en byte address.
37470 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
37480 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72  th argument, pAr
37490 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61  g, is an applica
374a0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
374b0 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
374c0 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74  .** through as t
374d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
374e0 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  t to the collati
374f0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
37500 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  back..**.** ^The
37510 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c   fifth argument,
37520 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61   xCallback, is a
37530 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
37540 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37550 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65  on..** ^Multiple
37560 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37570 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69  ions can be regi
37580 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
37590 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a   same name but.*
375a0 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  * with different
375b0 20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65   eTextRep parame
375c0 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20  ters and SQLite 
375d0 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76  will use whichev
375e0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  er.** function r
375f0 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73  equires the leas
37600 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
37610 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e   transformation.
37620 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c  .** ^If the xCal
37630 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69  lback argument i
37640 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
37650 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37660 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64  on is.** deleted
37670 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c  .  ^When all col
37680 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
37690 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65   having the same
376a0 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65   name are delete
376b0 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61  d,.** that colla
376c0 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  tion is no longe
376d0 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  r usable..**.** 
376e0 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  ^The collating f
376f0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
37700 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
37710 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70   a copy of the p
37720 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74  Arg .** applicat
37730 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
37740 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74   and with two st
37750 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63  rings in the enc
37760 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a  oding specified.
37770 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52  ** by the eTextR
37780 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  ep argument.  Th
37790 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
377a0 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e  tion must return
377b0 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74   an.** integer t
377c0 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c  hat is negative,
377d0 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69   zero, or positi
377e0 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72  ve.** if the fir
377f0 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73  st string is les
37800 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f  s than, equal to
37810 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  , or greater tha
37820 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a  n the second,.**
37830 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
37840 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  A collating func
37850 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73  tion must always
37860 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
37870 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e   answer.** given
37880 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73   the same inputs
37890 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  .  If two or mor
378a0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
378b0 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74  tions are regist
378c0 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ered.** to the s
378d0 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61  ame collation na
378e0 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72  me (using differ
378f0 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c  ent eTextRep val
37900 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a  ues) then all.**
37910 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71   must give an eq
37920 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20  uivalent answer 
37930 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74  when invoked wit
37940 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72  h equivalent str
37950 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c  ings..** The col
37960 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
37970 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f  must obey the fo
37980 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69  llowing properti
37990 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74  es for all.** st
379a0 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20  rings A, B, and 
379b0 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  C:.**.** <ol>.**
379c0 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68   <li> If A==B th
379d0 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e  en B==A..** <li>
379e0 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d   If A==B and B==
379f0 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20  C then A==C..** 
37a00 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54  <li> If A&lt;B T
37a10 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c  HEN B&gt;A..** <
37a20 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e  li> If A&lt;B an
37a30 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26  d B&lt;C then A&
37a40 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  lt;C..** </ol>.*
37a50 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74  *.** If a collat
37a60 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69  ing function fai
37a70 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62  ls any of the ab
37a80 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  ove constraints 
37a90 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c  and that.** coll
37aa0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
37ab0 73 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  s  registered an
37ac0 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  d used, then the
37ad0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
37ae0 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ite.** is undefi
37af0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
37b00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37b10 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f  ollation_v2() wo
37b20 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
37b30 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37b40 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  n().** with the 
37b50 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68  addition that th
37b60 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
37b70 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
37b80 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74  n pArg when.** t
37b90 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
37ba0 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
37bb0 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20  ..** ^Collating 
37bc0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65  functions are de
37bd0 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20  leted when they 
37be0 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
37bf0 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73  y later.** calls
37c00 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   to the collatio
37c10 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74  n creation funct
37c20 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65  ions or when the
37c30 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
37c40 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f  nnection] is clo
37c50 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  sed using [sqlit
37c60 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
37c70 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79  ** ^The xDestroy
37c80 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e   callback is <u>
37c90 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69  not</u> called i
37ca0 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65  f the .** sqlite
37cb0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37cc0 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e  on_v2() function
37cd0 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61   fails.  Applica
37ce0 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b  tions that invok
37cf0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  e.** sqlite3_cre
37d00 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
37d10 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  () with a non-NU
37d20 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75  LL xDestroy argu
37d30 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  ment should .** 
37d40 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
37d50 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73   code and dispos
37d60 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
37d70 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
37d80 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20  r.** themselves 
37d90 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65  rather than expe
37da0 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20  cting SQLite to 
37db0 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72  deal with it for
37dc0 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69   them..** This i
37dd0 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  s different from
37de0 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c   every other SQL
37df0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
37e00 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63  The inconsistenc
37e10 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75  y .** is unfortu
37e20 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20  nate but cannot 
37e30 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f  be changed witho
37e40 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b  ut breaking back
37e50 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74  wards .** compat
37e60 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53  ibility..**.** S
37e70 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74  ee also:  [sqlit
37e80 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
37e90 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ded()] and [sqli
37ea0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37eb0 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  eded16()]..*/.in
37ec0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
37ed0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
37ee0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
37ef0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
37f00 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
37f10 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
37f20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
37f30 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
37f40 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
37f50 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
37f60 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37f70 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
37f80 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
37f90 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
37fa0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
37fb0 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
37fc0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
37fd0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
37fe0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
37ff0 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
38000 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
38010 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
38020 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
38030 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
38040 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
38050 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
38060 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
38070 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
38080 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
38090 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
380a0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
380b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
380c0 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43  llation Needed C
380d0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
380e0 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20  To avoid having 
380f0 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20  to register all 
38100 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
38110 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74  ces before a dat
38120 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20  abase.** can be 
38130 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63  used, a single c
38140 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
38150 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
38160 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
38170 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
38180 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b  ion] to be invok
38190 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75  ed whenever an u
381a0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
381b0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69  on.** sequence i
381c0 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
381d0 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  * ^If the functi
381e0 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64  on is registered
381f0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
38200 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
38210 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68  ded() API,.** th
38220 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20  en it is passed 
38230 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64  the names of und
38240 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
38250 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74   sequences as st
38260 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64  rings.** encoded
38270 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73   in UTF-8. ^If s
38280 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
38290 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75  _needed16() is u
382a0 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  sed,.** the name
382b0 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  s are passed as 
382c0 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e  UTF-16 in machin
382d0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
382e0 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  der..** ^A call 
382f0 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69  to either functi
38300 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20  on replaces the 
38310 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69  existing collati
38320 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61  on-needed callba
38330 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e  ck..**.** ^(When
38340 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
38350 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
38360 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
38370 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
38380 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
38390 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
383a0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
383b0 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
383c0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
383d0 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
383e0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
383f0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
38400 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
38410 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
38420 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
38430 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
38440 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
38450 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
38460 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
38470 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
38480 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
38490 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
384a0 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
384b0 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
384c0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
384d0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
384e0 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
384f0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
38500 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  )^.**.** The cal
38510 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73  lback function s
38520 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74  hould register t
38530 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61  he desired colla
38540 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
38550 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
38560 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  llation()], [sql
38570 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
38580 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ation16()], or.*
38590 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
385a0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
385b0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
385c0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
385d0 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
385e0 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
385f0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
38600 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
38610 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
38620 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
38630 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
38640 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
38650 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29  void*,.  void(*)
38660 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
38670 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
38680 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69  st void*).);..#i
38690 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f  fdef SQLITE_HAS_
386a0 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CODEC./*.** Spec
386b0 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
386c0 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
386d0 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
386e0 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
386f0 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
38700 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
38710 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
38720 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
38730 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
38740 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
38750 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
38760 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
38770 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  /.int sqlite3_ke
38780 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
38790 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
387a0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
387b0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
387c0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
387d0 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
387e0 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
387f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b  );.int sqlite3_k
38800 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  ey_v2(.  sqlite3
38810 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
38820 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
38830 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
38840 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  d */.  const ch