/ Hex Artifact Content
Login

Artifact 8f704473c8301f3c9cc044d10020bb3d5955dfc3:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  y are supported 
07d0: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
07e0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
07f0: 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
0800: 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64  n writers should
0810: 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a   be aware that.*
0820: 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  * experimental i
0830: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75  nterfaces are su
0840: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
0850: 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65  in point release
0860: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d  s..**.** These m
0870: 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65  acros used to re
0880: 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73  solve to various
0890: 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c   kinds of compil
08a0: 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a  er magic that.**
08b0: 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20   would generate 
08c0: 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73  warning messages
08d0: 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65 20   when they were 
08e0: 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a  used.  But that.
08f0: 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69  ** compiler magi
0900: 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72  c ended up gener
0910: 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75  ating such a flu
0920: 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72  rry of bug repor
0930: 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61  ts.** that we ha
0940: 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20  ve taken it all 
0950: 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63  out and gone bac
0960: 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c  k to using simpl
0970: 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73  e.** noop macros
0980: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
0990: 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23  ITE_DEPRECATED.#
09a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
09b0: 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a  PERIMENTAL../*.*
09c0: 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20 73  * Ensure these s
09d0: 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20  ymbols were not 
09e0: 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20  defined by some 
09f0: 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 20  previous header 
0a00: 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  file..*/.#ifdef 
0a10: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23  SQLITE_VERSION.#
0a20: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0a30: 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66  RSION.#endif.#if
0a40: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0a50: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65  ON_NUMBER.# unde
0a60: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a70: 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a  _NUMBER.#endif..
0a80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
0a90: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62  Compile-Time Lib
0aa0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0ab0: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  bers.**.** ^(The
0ac0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ad0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0ae0: 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71   macro in the sq
0af0: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a  lite3.h header.*
0b00: 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61  * evaluates to a
0b10: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20   string literal 
0b20: 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69  that is the SQLi
0b30: 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68  te version in th
0b40: 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59  e.** format "X.Y
0b50: 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20 74  .Z" where X is t
0b60: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e  he major version
0b70: 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20   number (always 
0b80: 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33  3 for.** SQLite3
0b90: 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d  ) and Y is the m
0ba0: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  inor version num
0bb0: 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65  ber and Z is the
0bc0: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e   release number.
0bd0: 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  )^.** ^(The [SQL
0be0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bf0: 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ER] C preprocess
0c00: 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65  or macro resolve
0c10: 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  s to an integer.
0c20: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c 75  ** with the valu
0c30: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0c40: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0c50: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65   X, Y, and Z are
0c60: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d   the same.** num
0c70: 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51  bers used in [SQ
0c80: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e  LITE_VERSION].)^
0c90: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56  .** The SQLITE_V
0ca0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f  ERSION_NUMBER fo
0cb0: 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65  r any given rele
0cc0: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ase of SQLite wi
0cd0: 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61  ll also.** be la
0ce0: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72 65  rger than the re
0cf0: 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  lease from which
0d00: 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e 20   it is derived. 
0d10: 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a   Either Y will.*
0d20: 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61  * be held consta
0d30: 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  nt and Z will be
0d40: 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20   incremented or 
0d50: 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69  else Y will be i
0d60: 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e  ncremented.** an
0d70: 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65  d Z will be rese
0d80: 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t to zero..**.**
0d90: 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33   Since version 3
0da0: 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f  .6.18, SQLite so
0db0: 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 62 65  urce code has be
0dc0: 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  en stored in the
0dd0: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74  .** <a href="htt
0de0: 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73  p://www.fossil-s
0df0: 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20  cm.org/">Fossil 
0e00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0e10: 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74  nagement.** syst
0e20: 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51  em</a>.  ^The SQ
0e30: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d  LITE_SOURCE_ID m
0e40: 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74  acro evaluates t
0e50: 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68  o.** a string wh
0e60: 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 20 61  ich identifies a
0e70: 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 65 63   particular chec
0e80: 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a  k-in of SQLite.*
0e90: 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e  * within its con
0ea0: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67  figuration manag
0eb0: 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e  ement system.  ^
0ec0: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  The SQLITE_SOURC
0ed0: 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63  E_ID.** string c
0ee0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 65  ontains the date
0ef0: 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65   and time of the
0f00: 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20   check-in (UTC) 
0f10: 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68  and an SHA1.** h
0f20: 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72  ash of the entir
0f30: 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a  e source tree..*
0f40: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
0f50: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0f60: 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  on()],.** [sqlit
0f70: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
0f80: 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65  mber()], [sqlite
0f90: 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a  3_sourceid()],.*
0fa0: 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  * [sqlite_versio
0fb0: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
0fc0: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
0fd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
0fe0: 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20  _VERSION        
0ff0: 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69  "--VERS--".#defi
1000: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
1010: 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49  N_NUMBER --VERSI
1020: 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66  ON-NUMBER--.#def
1030: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1040: 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55  E_ID      "--SOU
1050: 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a  RCE-ID--"../*.**
1060: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
1070: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
1080: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
1090: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10a0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
10b0: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
10c0: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
10d0: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
10e0: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
10f0: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1100: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1110: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1120: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1130: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1140: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
1150: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
1160: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1170: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
1180: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
1190: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11a0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
11b0: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
11c0: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
11d0: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
11e0: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
11f0: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1200: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1210: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1220: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1230: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1240: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
1250: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
1260: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
1270: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
1280: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
1290: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12a0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
12b0: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
12c0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
12d0: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
12e0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
12f0: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1300: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1310: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1320: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1330: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1340: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
1350: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
1360: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
1370: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1380: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
1390: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13a0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
13b0: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
13c0: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
13d0: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
13e0: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
13f0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1400: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1410: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1420: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1430: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1440: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
1450: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
1460: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
1470: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
1480: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
1490: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14a0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
14b0: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
14c0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
14d0: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
14e0: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
14f0: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1500: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1510: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1520: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1530: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1540: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
1550: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
1560: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
1570: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
1580: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
1590: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15a0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
15b0: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
15c0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
15d0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
15e0: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
15f0: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1600: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1610: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1620: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ()]..*/.SQLITE_E
1630: 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72  XTERN const char
1640: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
1650: 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  [];.const char *
1660: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1670: 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20  on(void);.const 
1680: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1690: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e  urceid(void);.in
16a0: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  t sqlite3_libver
16b0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
16c0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16d0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
16e0: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e  rary Compilation
16f0: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73   Options Diagnos
1700: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tics.**.** ^The 
1710: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1720: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e  ption_used() fun
1730: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20  ction returns 0 
1740: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74  or 1 .** indicat
1750: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20  ing whether the 
1760: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e  specified option
1770: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20   was defined at 
1780: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
1790: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
17a0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d  prefix may be om
17b0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a  itted from the .
17c0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70  ** option name p
17d0: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
17e0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
17f0: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  sed().  .**.** ^
1800: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
1810: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1820: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  function allows 
1830: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65  iterating.** ove
1840: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70  r the list of op
1850: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20  tions that were 
1860: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69  defined at compi
1870: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65  le time by.** re
1880: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68  turning the N-th
1890: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70   compile time op
18a0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49  tion string.  ^I
18b0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
18c0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  nge,.** sqlite3_
18d0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
18e0: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  t() returns a NU
18f0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
1900: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72  e SQLITE_ .** pr
1910: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20  efix is omitted 
1920: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73  from any strings
1930: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
1940: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1950: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a  option_get()..**
1960: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72  .** ^Support for
1970: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20   the diagnostic 
1980: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65  functions sqlite
1990: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
19a0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71  used().** and sq
19b0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
19c0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65  ion_get() may be
19d0: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63   omitted by spec
19e0: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b  ifying the .** [
19f0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1a00: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d  ILEOPTION_DIAGS]
1a10: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69   option at compi
1a20: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53  le time..**.** S
1a30: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e  ee also: SQL fun
1a40: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63  ctions [sqlite_c
1a50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1a60: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1a70: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1a80: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65  n_get()] and the
1a90: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e   [compile_option
1aa0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69  s pragma]..*/.#i
1ab0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
1ac0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
1ad0: 44 49 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65  DIAGS.int sqlite
1ae0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1af0: 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20  used(const char 
1b00: 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73  *zOptName);.cons
1b10: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1b20: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b30: 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66  t(int N);.#endif
1b40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b50: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1b60: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1b70: 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a  Threadsafe.**.**
1b80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68   ^The sqlite3_th
1b90: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
1ba0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ion returns zero
1bb0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
1bc0: 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  ** SQLite was co
1bd0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
1be0: 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65  xing code omitte
1bf0: 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20  d due to the.** 
1c00: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1c10: 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  FE] compile-time
1c20: 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65   option being se
1c30: 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51  t to 0..**.** SQ
1c40: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70  Lite can be comp
1c50: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74  iled with or wit
1c60: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57  hout mutexes.  W
1c70: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  hen.** the [SQLI
1c80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43  TE_THREADSAFE] C
1c90: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1ca0: 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d  cro is 1 or 2, m
1cb0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1cc0: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1cd0: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1ce0: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51   When the.** [SQ
1cf0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d00: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a   macro is 0, .**
1d10: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
1d20: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
1d30: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
1d40: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
1d50: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
1d60: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
1d70: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
1d80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
1d90: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
1da0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
1db0: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
1dc0: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
1dd0: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
1de0: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
1df0: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
1e00: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
1e10: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
1e20: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
1e30: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
1e40: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
1e50: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65   ^The default be
1e60: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75  havior is for mu
1e70: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62  texes to be enab
1e80: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  led..**.** This 
1e90: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1ea0: 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c   used by an appl
1eb0: 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20  ication to make 
1ec0: 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1ed0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
1ee0: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69  te that it is li
1ef0: 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61  nking against wa
1f00: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
1f10: 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73  ** the desired s
1f20: 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53  etting of the [S
1f30: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f40: 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54  ] macro..**.** T
1f50: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  his interface on
1f60: 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68  ly reports on th
1f70: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
1f80: 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20  utex setting.** 
1f90: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1fa0: 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e  HREADSAFE] flag.
1fb0: 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
1fc0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
1fd0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fe0: 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d  E=1 or =2 then m
1ff0: 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c  utexes are enabl
2000: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75  ed by default bu
2010: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c  t.** can be full
2020: 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64  y or partially d
2030: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
2040: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2050: 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69  _config()].** wi
2060: 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51  th the verbs [SQ
2070: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2080: 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49  LETHREAD], [SQLI
2090: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
20a0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  HREAD],.** or [S
20b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
20c0: 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75  EX].  ^(The retu
20d0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a  rn value of the.
20e0: 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  ** sqlite3_threa
20f0: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
2100: 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20   shows only the 
2110: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74  compile-time set
2120: 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61  ting of.** threa
2130: 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e  d safety, not an
2140: 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67  y run-time chang
2150: 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74 69  es to that setti
2160: 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71  ng made by.** sq
2170: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20  lite3_config(). 
2180: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2190: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
21a0: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68   from sqlite3_th
21b0: 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73  readsafe().** is
21c0: 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61   unchanged by ca
21d0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
21e0: 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  onfig().)^.**.**
21f0: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64   See the [thread
2200: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65  ing mode] docume
2210: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
2220: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
2230: 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  on..*/.int sqlit
2240: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f  e3_threadsafe(vo
2250: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
2260: 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
2270: 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65  onnection Handle
2280: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
2290: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22a0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
22b0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
22c0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
22d0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
22e0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
22f0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
2300: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
2310: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
2320: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
2330: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
2340: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
2350: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
2360: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
2370: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
2380: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
2390: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
23a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
23b0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
23c0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
23d0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
23e0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
23f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2400: 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73  se_v2()] are its
2410: 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54   destructors.  T
2420: 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74  here are many ot
2430: 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  her.** interface
2440: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2450: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2460: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
2470: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2480: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2490: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
24a0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
24b0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
24c0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
24d0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
24e0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
24f0: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
2500: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
2510: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2520: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2530: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2540: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2550: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2560: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
2570: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
2580: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
2590: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
25a0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
25b0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
25c0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
25d0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
25e0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
25f0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
2600: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
2610: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2620: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2630: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2640: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2650: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2660: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
2670: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
2680: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
2690: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
26a0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
26b0: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
26c0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
26d0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
26e0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
26f0: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
2700: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2710: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2720: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2730: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2740: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2750: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2760: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
2770: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
2780: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
2790: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
27a0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
27b0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
27c0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
27d0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
27e0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
27f0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
2800: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
2810: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2820: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2830: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2840: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2850: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2860: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2870: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2880: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2890: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
28a0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
28b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
28c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
28d0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
28e0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
28f0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
2900: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
2910: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2920: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2930: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2940: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2950: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2960: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2970: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2980: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2990: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
29a0: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
29b0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
29c0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
29d0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
29e0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
29f0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2a00: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
2a10: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2a20: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
2a30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2a40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
2a50: 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73  se_v2() routines
2a60: 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 73   are destructors
2a70: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  .** for the [sql
2a80: 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ite3] object..**
2a90: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
2aa0: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73  e3_close() and s
2ab0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2ac0: 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  ) return [SQLITE
2ad0: 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b  _OK] if.** the [
2ae0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2af0: 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  is successfully 
2b00: 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c  destroyed and al
2b10: 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  l associated.** 
2b20: 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64 65  resources are de
2b30: 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  allocated..**.**
2b40: 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
2b50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2b60: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2b70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2b80: 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2b90: 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  ts or unfinished
2ba0: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2bb0: 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c  objects then sql
2bc0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20  ite3_close().** 
2bd0: 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64  will leave the d
2be0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2bf0: 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75  on open and retu
2c00: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
2c10: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
2c20: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63  _close_v2() is c
2c30: 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e  alled with unfin
2c40: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 20  alized prepared 
2c50: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e  statements.** an
2c60: 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20  d/or unfinished 
2c70: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c  sqlite3_backups,
2c80: 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
2c90: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  se connection be
2ca0: 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73  comes.** an unus
2cb0: 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68  able "zombie" wh
2cc0: 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ich will automat
2cd0: 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f  ically be deallo
2ce0: 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a  cated when the.*
2cf0: 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 20  * last prepared 
2d00: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e  statement is fin
2d10: 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61  alized or the la
2d20: 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  st sqlite3_backu
2d30: 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64  p is.** finished
2d40: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  .  The sqlite3_c
2d50: 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66  lose_v2() interf
2d60: 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ace is intended 
2d70: 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20  for use with.** 
2d80: 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74  host languages t
2d90: 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65 20  hat are garbage 
2da0: 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77  collected, and w
2db0: 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20 69  here the order i
2dc0: 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72  n which.** destr
2dd0: 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65  uctors are calle
2de0: 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a  d is arbitrary..
2df0: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
2e00: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
2e10: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
2e20: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
2e30: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2e40: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2e50: 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73  lob_close | clos
2e60: 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e  e] all [BLOB han
2e70: 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b  dles], and .** [
2e80: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66  sqlite3_backup_f
2e90: 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20  inish | finish] 
2ea0: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  all [sqlite3_bac
2eb0: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73  kup] objects ass
2ec0: 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
2ed0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2ee0: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
2ef0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
2f00: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e  e the object.  ^
2f10: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c  If.** sqlite3_cl
2f20: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  ose_v2() is call
2f30: 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73  ed on a [databas
2f40: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
2f50: 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20  at still has.** 
2f60: 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65  outstanding [pre
2f70: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2f80: 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ], [BLOB handles
2f90: 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71  ], and/or.** [sq
2fa0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2fb0: 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72 65  jects then it re
2fc0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
2fd0: 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f  ] and the deallo
2fe0: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73  cation.** of res
2ff0: 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72 72  ources is deferr
3000: 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72  ed until all [pr
3010: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3020: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3030: 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  s],.** and [sqli
3040: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
3050: 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73  cts are also des
3060: 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  troyed..**.** ^I
3070: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  f an [sqlite3] o
3080: 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79  bject is destroy
3090: 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73  ed while a trans
30a0: 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a  action is open,.
30b0: 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ** the transacti
30c0: 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  on is automatica
30d0: 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  lly rolled back.
30e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72  .**.** The C par
30f0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
3100: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64  e3_close(C)] and
3110: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
3120: 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  v2(C)].** must b
3130: 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a  e either a NULL.
3140: 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e  ** pointer or an
3150: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3160: 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e  t pointer obtain
3170: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
3180: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
3190: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
31a0: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
31b0: 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
31c0: 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63  not previously c
31d0: 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69  losed..** ^Calli
31e0: 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  ng sqlite3_close
31f0: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c  () or sqlite3_cl
3200: 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 20  ose_v2() with a 
3210: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
3220: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61  argument is a ha
3230: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f  rmless no-op..*/
3240: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f  .int sqlite3_clo
3250: 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e  se(sqlite3*);.in
3260: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  t sqlite3_close_
3270: 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  v2(sqlite3*);../
3280: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
3290: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
32a0: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
32b0: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
32c0: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
32d0: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
32e0: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
32f0: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
3300: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
3310: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
3320: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
3330: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
3340: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
3350: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
3360: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
3370: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
3380: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
3390: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
33a0: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
33b0: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
33c0: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
33d0: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
33e0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
33f0: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
3400: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
3410: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
3420: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
3430: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
3440: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
3450: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3460: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3470: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3480: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3490: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
34a0: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
34b0: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
34c0: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
34d0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
34e0: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
34f0: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
3500: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
3510: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
3520: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
3530: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
3540: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
3550: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3560: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3570: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3580: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3590: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
35a0: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
35b0: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
35c0: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
35d0: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
35e0: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
35f0: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
3600: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
3610: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3620: 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67  s relayed throug
3630: 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67  h to the 1st arg
3640: 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a  ument of each.**
3650: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61   callback invoca
3660: 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63  tion.  ^If the c
3670: 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20  allback pointer 
3680: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3690: 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ).** is NULL, th
36a0: 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69  en no callback i
36b0: 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61  s ever invoked a
36c0: 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61  nd result rows a
36d0: 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a  re.** ignored..*
36e0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f  *.** ^If an erro
36f0: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65  r occurs while e
3700: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51  valuating the SQ
3710: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
3720: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  sed into.** sqli
3730: 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e  te3_exec(), then
3740: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
3750: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d  e current statem
3760: 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a  ent stops and.**
3770: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74   subsequent stat
3780: 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70  ements are skipp
3790: 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68  ed.  ^If the 5th
37a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
37b0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
37c0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
37d0: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
37e0: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
37f0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
3800: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
3810: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
3820: 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  d passed back th
3830: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
3840: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61  rameter..** To a
3850: 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  void memory leak
3860: 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  s, the applicati
3870: 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65  on should invoke
3880: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3890: 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65  ].** on error me
38a0: 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65  ssage strings re
38b0: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
38c0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
38d0: 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65   of.** of sqlite
38e0: 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74  3_exec() after t
38f0: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
3900: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f   string is no lo
3910: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20  nger needed..** 
3920: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
3930: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3940: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3950: 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72  ULL and no error
3960: 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e  s.** occur, then
3970: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3980: 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72  sets the pointer
3990: 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61   in its 5th para
39a0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c  meter to.** NULL
39b0: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
39c0: 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  g..**.** ^If an 
39d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
39e0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
39f0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71  non-zero, the sq
3a00: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3a10: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
3a20: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74  SQLITE_ABORT wit
3a30: 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  hout invoking th
3a40: 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e  e callback again
3a50: 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20   and.** without 
3a60: 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73  running any subs
3a70: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
3a80: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
3a90: 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  e 2nd argument t
3aa0: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
3ab0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75  ec() callback fu
3ac0: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a  nction is the.**
3ad0: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
3ae0: 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
3af0: 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75  .  ^The 3rd argu
3b00: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
3b10: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61  te3_exec().** ca
3b20: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
3b30: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3b40: 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e  o strings obtain
3b50: 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a  ed as if from.**
3b60: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
3b70: 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f  _text()], one fo
3b80: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20  r each column.  
3b90: 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f  ^If an element o
3ba0: 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  f a.** result ro
3bb0: 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  w is NULL then t
3bc0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
3bd0: 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
3be0: 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  for the.** sqlit
3bf0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3c00: 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ck is a NULL poi
3c10: 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20  nter.  ^The 4th 
3c20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
3c30: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3c40: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  ) callback is an
3c50: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3c60: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68  rs to strings wh
3c70: 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72  ere each.** entr
3c80: 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65  y represents the
3c90: 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70   name of corresp
3ca0: 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f  onding result co
3cb0: 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64  lumn as obtained
3cc0: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3cd0: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
3ce0: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
3cf0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
3d00: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3d10: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
3d20: 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  r, a pointer.** 
3d30: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
3d40: 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ng, or a pointer
3d50: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f   that contains o
3d60: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
3d70: 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f  nd/or .** SQL co
3d80: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20  mments, then no 
3d90: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
3da0: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
3db0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
3dc0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e   is not changed.
3dd0: 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69  .**.** Restricti
3de0: 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ons:.**.** <ul>.
3df0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3e00: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73  ication must ins
3e10: 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74  ure that the 1st
3e20: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3e30: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3e40: 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20       is a valid 
3e50: 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  and open [databa
3e60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
3e70: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3e80: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3e90: 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61   close the [data
3ea0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
3eb0: 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
3ec0: 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61        the 1st pa
3ed0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3ee0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
3ef0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3f00: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c  s running..** <l
3f10: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3f20: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69  on must not modi
3f30: 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  fy the SQL state
3f40: 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64  ment text passed
3f50: 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68   into.**      th
3f60: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
3f70: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3f80: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
3f90: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
3fa0: 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69  g..** </ul>.*/.i
3fb0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
3fc0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3ff0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
4000: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
4010: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
4040: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4050: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4060: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4070: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4080: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4090: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
40c0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
40d0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
40e0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
4110: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
4120: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
4130: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
4140: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4150: 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64  RDS: {result cod
4160: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a  e definitions}.*
4170: 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65  *.** Many SQLite
4180: 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
4190: 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73  n an integer res
41a0: 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68  ult code from th
41b0: 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68  e set shown.** h
41c0: 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ere in order to 
41d0: 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73 73  indicate success
41e0: 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a   or failure..**.
41f0: 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64  ** New error cod
4200: 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
4210: 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
4220: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
4230: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65  .** See also: [e
4240: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4250: 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d  ode definitions]
4260: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4270: 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20  TE_OK           
4280: 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75  0   /* Successfu
4290: 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62  l result */./* b
42a0: 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f  eginning-of-erro
42b0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69  r-codes */.#defi
42c0: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  ne SQLITE_ERROR 
42d0: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51         1   /* SQ
42e0: 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69  L error or missi
42f0: 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ng database */.#
4300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4310: 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f  TERNAL     2   /
4320: 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63  * Internal logic
4330: 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65   error in SQLite
4340: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4350: 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20  TE_PERM         
4360: 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65  3   /* Access pe
4370: 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20  rmission denied 
4380: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4390: 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34  E_ABORT        4
43a0: 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72     /* Callback r
43b0: 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64  outine requested
43c0: 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65   an abort */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
43e0: 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20           5   /* 
43f0: 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  The database fil
4400: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
4410: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4420: 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f  CKED       6   /
4430: 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65  * A table in the
4440: 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63   database is loc
4450: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4460: 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20  QLITE_NOMEM     
4470: 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c     7   /* A mall
4480: 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23  oc() failed */.#
4490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
44a0: 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f  ADONLY     8   /
44b0: 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69  * Attempt to wri
44c0: 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61  te a readonly da
44d0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
44e0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55  e SQLITE_INTERRU
44f0: 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65  PT    9   /* Ope
4500: 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65  ration terminate
4510: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74  d by sqlite3_int
4520: 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69  errupt()*/.#defi
4530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  ne SQLITE_IOERR 
4540: 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f        10   /* So
4550: 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20  me kind of disk 
4560: 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72  I/O error occurr
4570: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4580: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20  LITE_CORRUPT    
4590: 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74   11   /* The dat
45a0: 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65  abase disk image
45b0: 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f   is malformed */
45c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
45d0: 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20  NOTFOUND    12  
45e0: 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f   /* Unknown opco
45f0: 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69  de in sqlite3_fi
4600: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a  le_control() */.
4610: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4620: 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20  ULL        13   
4630: 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69  /* Insertion fai
4640: 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61  led because data
4650: 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a  base is full */.
4660: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4670: 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20  ANTOPEN    14   
4680: 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65  /* Unable to ope
4690: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
46a0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
46b0: 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20  QLITE_PROTOCOL  
46c0: 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61    15   /* Databa
46d0: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
46e0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
46f0: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
4700: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
4710: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
4720: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4730: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
4740: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4750: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
4760: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4770: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
4780: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
4790: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
47a0: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
47b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
47c0: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
47d0: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
47e0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
47f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4800: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
4810: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
4820: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
4830: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
4840: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
4850: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
4860: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
4880: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
4890: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
48a0: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
48b0: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
48c0: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
48d0: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
48e0: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
48f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4900: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
4910: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
4920: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
4930: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
4940: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
4950: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
4960: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
4970: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
4980: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
4990: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
49a0: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
49b0: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
49c0: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
49d0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
49e0: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20   SQLITE_NOTICE  
49f0: 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69      27   /* Noti
4a00: 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73  fications from s
4a10: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4a20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57  #define SQLITE_W
4a30: 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20  ARNING     28   
4a40: 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d  /* Warnings from
4a50: 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a   sqlite3_log() *
4a60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4a70: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
4a80: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4a90: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
4aa0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4ac0: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4ad0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4ae0: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4af0: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4b00: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4b10: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4b20: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4b30: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4b40: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
4b50: 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69  result code defi
4b60: 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49  nitions}.**.** I
4b70: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4b80: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4b90: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4ba0: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33   return one of 3
4bb0: 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65  0 integer.** [re
4bc0: 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f  sult codes].  Ho
4bd0: 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63  wever, experienc
4be0: 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74  e has shown that
4bf0: 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73   many of.** thes
4c00: 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  e result codes a
4c10: 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72  re too coarse-gr
4c20: 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20  ained.  They do 
4c30: 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a  not provide as.*
4c40: 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69  * much informati
4c50: 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d  on about problem
4c60: 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  s as programmers
4c70: 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e   might like.  In
4c80: 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a   an effort to.**
4c90: 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e   address this, n
4ca0: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
4cb0: 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e   SQLite (version
4cc0: 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72   3.3.8 and later
4cd0: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
4ce0: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
4cf0: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
4d00: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
4d10: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
4d20: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
4d30: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
4d40: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4d50: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
4d60: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
4d70: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
4d80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
4d90: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
4da0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
4db0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
4dc0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
4dd0: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
4de0: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
4df0: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
4e00: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
4e10: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
4e20: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
4e30: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
4e40: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
4e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
4e60: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
4e70: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4e80: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
4e90: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
4ea0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
4eb0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4ec0: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
4ed0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4ee0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
4ef0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f00: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
4f10: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f20: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
4f30: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4f40: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
4f50: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
4f60: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
4f70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f80: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
4f90: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4fa0: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
4fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4fc0: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
4fd0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4fe0: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
4ff0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5000: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
5010: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5020: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
5030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5040: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
5050: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5060: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
5070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5080: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
5090: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50a0: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
50b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50c0: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
50d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50e0: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
50f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5100: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5110: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5120: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5140: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5150: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5160: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5180: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
5190: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
51a0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
51b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
51c0: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
51d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51e0: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
51f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5200: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
5210: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5220: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
5230: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5240: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
5250: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5260: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
5270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5280: 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20  RR_SHMOPEN      
5290: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
52a0: 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64  RR | (18<<8)).#d
52b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
52c0: 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20  RR_SHMSIZE      
52d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
52e0: 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64  RR | (19<<8)).#d
52f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5300: 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20  RR_SHMLOCK      
5310: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5320: 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64  RR | (20<<8)).#d
5330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5340: 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20  RR_SHMMAP       
5350: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5360: 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64  RR | (21<<8)).#d
5370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5380: 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20  RR_SEEK         
5390: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53a0: 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64  RR | (22<<8)).#d
53b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53c0: 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20  RR_DELETE_NOENT 
53d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53e0: 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64  RR | (23<<8)).#d
53f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5400: 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20  RR_MMAP         
5410: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5420: 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64  RR | (24<<8)).#d
5430: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5440: 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20  RR_GETTEMPPATH  
5450: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5460: 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64  RR | (25<<8)).#d
5470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5480: 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  RR_CONVPATH     
5490: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
54a0: 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64  RR | (26<<8)).#d
54b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
54c0: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
54d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
54e0: 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  KED |  (1<<8)).#
54f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5500: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  SY_RECOVERY     
5510: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5520: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a  SY   |  (1<<8)).
5530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
5540: 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20  USY_SNAPSHOT    
5550: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
5560: 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29  USY   |  (2<<8))
5570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5580: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
5590: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
55a0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
55b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
55c0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
55d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
55e0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
55f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5600: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
5610: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
5620: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5630: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5640: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43  QLITE_CANTOPEN_C
5650: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53  ONVPATH       (S
5660: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5670: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5680: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5690: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
56a0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
56b0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
56c0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
56d0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
56e0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
56f0: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5700: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5710: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5720: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5730: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5740: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5750: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5760: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5770: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5780: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5790: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
57a0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
57b0: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
57c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
57d0: 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20  _ABORT_ROLLBACK 
57e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
57f0: 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29  _ABORT | (2<<8))
5800: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5810: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b  CONSTRAINT_CHECK
5820: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5830: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c  CONSTRAINT | (1<
5840: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5850: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5860: 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c  OMMITHOOK   (SQL
5870: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5880: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5890: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
58a0: 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20  NT_FOREIGNKEY   
58b0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
58c0: 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  NT | (3<<8)).#de
58d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
58e0: 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20  TRAINT_FUNCTION 
58f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5900: 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29  TRAINT | (4<<8))
5910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5920: 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55  CONSTRAINT_NOTNU
5930: 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  LL      (SQLITE_
5940: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c  CONSTRAINT | (5<
5950: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5960: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50  ITE_CONSTRAINT_P
5970: 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c  RIMARYKEY   (SQL
5980: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5990: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
59a0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
59b0: 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  NT_TRIGGER      
59c0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59d0: 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  NT | (7<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
59f0: 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20  TRAINT_UNIQUE   
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5a10: 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29  TRAINT | (8<<8))
5a20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a30: 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20  CONSTRAINT_VTAB 
5a40: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5a50: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c  CONSTRAINT | (9<
5a60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52  ITE_CONSTRAINT_R
5a80: 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c  OWID        (SQL
5a90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5aa0: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
5ab0: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5ac0: 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20  ECOVER_WAL      
5ad0: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5ae0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5af0: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5b00: 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20  ECOVER_ROLLBACK 
5b10: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5b20: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5b30: 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f   SQLITE_WARNING_
5b40: 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20  AUTOINDEX       
5b50: 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20  (SQLITE_WARNING 
5b60: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5b70: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53  e SQLITE_AUTH_US
5b80: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ER              
5b90: 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20   (SQLITE_AUTH | 
5ba0: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5bb0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
5bc0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
5bd0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
5be0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
5bf0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
5c00: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
5c10: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5c20: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5c30: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5c40: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5c50: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5c60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
5c70: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
5c80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c90: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
5ca0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5cb0: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
5cc0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5cd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ce0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
5cf0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5d00: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
5d10: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d30: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
5d40: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5d50: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
5d60: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d80: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
5d90: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
5da0: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
5db0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5dc0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
5dd0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5de0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
5df0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e00: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
5e10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5e20: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
5e30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e40: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
5e50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5e60: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
5e70: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5e80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e90: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
5ea0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5eb0: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
5ec0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5ed0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ee0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
5ef0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5f00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5f20: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
5f30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
5f40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5f60: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
5f70: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
5f80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5fa0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
5fb0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
5fc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5fd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5fe0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
5ff0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
6000: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6010: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6020: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
6030: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
6040: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6060: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
6070: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
6080: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6090: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
60a0: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
60b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
60c0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
60d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
60e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
60f0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
6100: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
6110: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6120: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6130: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6140: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6150: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
6160: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6170: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6180: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6190: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
61a0: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
61b0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
61c0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
61d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
61e0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
61f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
6200: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6210: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
6220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6230: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
6240: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
6250: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
6260: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
6270: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
6280: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
6290: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
62a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
62b0: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
62c0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
62d0: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
62e0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
62f0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
6300: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
6310: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
6320: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
6330: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
6340: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
6350: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
6360: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
6370: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
6380: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6390: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
63a0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
63b0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
63c0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
63d0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
63e0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
63f0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
6400: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
6410: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
6420: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
6430: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6440: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6450: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6460: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6470: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6480: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6490: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
64a0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
64b0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
64c0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
64d0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
64e0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
64f0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6500: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6510: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
6520: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
6530: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6540: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6550: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6560: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6570: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6580: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6590: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
65a0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
65b0: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
65c0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
65d0: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
65e0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
65f0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
6600: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6610: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
6620: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
6630: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6640: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6650: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6660: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6670: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6680: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6690: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
66a0: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
66b0: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
66c0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
66d0: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
66e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
66f0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6700: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
6710: 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  e that a file ca
6720: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
6730: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a  when open.  The.
6740: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ** SQLITE_IOCAP_
6750: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69  IMMUTABLE flag i
6760: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
6770: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20  e file is on.** 
6780: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20  read-only media 
6790: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  and cannot be ch
67a0: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72  anged even by pr
67b0: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20  ocesses with.** 
67c0: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65  elevated privile
67d0: 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ges..*/.#define 
67e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
67f0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
6800: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
6810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6820: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
6830: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6840: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6850: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6860: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
6870: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
6880: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6890: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
68a0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
68b0: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
68c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
68d0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
68e0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
68f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6900: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
6910: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
6920: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6930: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6940: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6950: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
6960: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6970: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
6980: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
6990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
69a0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
69b0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
69c0: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
69d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
69e0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
69f0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
6a00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6a10: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
6a20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6a30: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
6a40: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6a50: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
6a60: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
6a70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a80: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6a90: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
6aa0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6ab0: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
6ac0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  E              0
6ad0: 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00002000../*.**
6ae0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
6af0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
6b00: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
6b10: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
6b20: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6b30: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
6b40: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
6b50: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
6b60: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6b70: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
6b80: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6b90: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6ba0: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
6bb0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
6bc0: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6bd0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
6be0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
6bf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6c00: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
6c10: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
6c20: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
6c30: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6c40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6c50: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
6c60: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
6c70: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
6c80: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
6c90: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
6ca0: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
6cb0: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
6cc0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6cd0: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
6ce0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
6cf0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
6d00: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6d10: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
6d20: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
6d30: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
6d40: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
6d50: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
6d60: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
6d70: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
6d80: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
6d90: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
6da0: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
6db0: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
6dc0: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
6dd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6de0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
6df0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
6e00: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
6e10: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
6e20: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
6e30: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
6e40: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6e50: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
6e60: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
6e70: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
6e80: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
6e90: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
6ea0: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
6eb0: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
6ec0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6ed0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6ee0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
6ef0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
6f00: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6f10: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
6f20: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6f30: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
6f40: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
6f50: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
6f60: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
6f70: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
6f80: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
6f90: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
6fa0: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
6fb0: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
6fc0: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
6fd0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6fe0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6ff0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
7000: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
7010: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
7020: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
7030: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
7040: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
7050: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
7060: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
7070: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
7080: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
7090: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
70a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
70b0: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
70c0: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
70d0: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
70e0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
70f0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
7100: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
7110: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
7120: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
7130: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
7140: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
7150: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
7160: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
7170: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7180: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
7190: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
71a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
71b0: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
71c0: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
71d0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
71e0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
71f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7200: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
7210: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
7220: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
7230: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
7240: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
7250: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
7260: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
7270: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
7280: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
7290: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
72a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
72b0: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
72c0: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
72d0: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
72e0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
72f0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
7300: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
7310: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
7320: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
7330: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
7340: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7350: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
7360: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
7370: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
7380: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
7390: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
73a0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
73b0: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
73c0: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
73d0: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
73e0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
73f0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
7400: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
7410: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
7420: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
7430: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7440: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
7450: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
7460: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
7470: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
7480: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7490: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
74a0: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
74b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
74c0: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
74d0: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
74e0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
74f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7500: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
7510: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
7520: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
7530: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
7540: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
7550: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
7560: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
7570: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
7580: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
7590: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
75a0: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
75b0: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
75c0: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
75d0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
75e0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
75f0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7600: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
7610: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
7620: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
7630: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7640: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
7650: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
7660: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
7670: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7680: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
7690: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
76a0: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
76b0: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
76c0: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
76d0: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
76e0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
76f0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
7700: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7710: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
7720: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7730: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
7740: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
7750: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7760: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
7770: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
7780: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
7790: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
77a0: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
77b0: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
77c0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
77d0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
77e0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
77f0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
7800: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
7810: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
7820: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
7830: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
7840: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
7850: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
7860: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
7870: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
7880: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
7890: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
78a0: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
78b0: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
78c0: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
78d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
78e0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
78f0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
7900: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
7910: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
7920: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
7930: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7940: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
7950: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
7960: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
7970: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
7980: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
7990: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
79a0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
79b0: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
79c0: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
79d0: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
79e0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
79f0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
7a00: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
7a10: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
7a20: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
7a30: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
7a40: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
7a50: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
7a60: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
7a70: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
7a80: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
7a90: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
7aa0: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
7ab0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
7ac0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
7ad0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
7ae0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
7af0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
7b00: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7b10: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
7b20: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
7b30: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
7b40: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7b50: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
7b60: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
7b70: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
7b80: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
7b90: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
7ba0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
7bb0: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
7bc0: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
7bd0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
7be0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
7bf0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
7c00: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
7c10: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
7c20: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
7c30: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
7c40: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7c50: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
7c60: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
7c70: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
7c80: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
7c90: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
7ca0: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
7cb0: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
7cc0: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
7cd0: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
7ce0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
7cf0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
7d00: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
7d10: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
7d20: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
7d30: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
7d40: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
7d50: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
7d60: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f  * A [file contro
7d70: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74  l opcodes | list
7d80: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
7d90: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
7da0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
7db0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
7dc0: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7dd0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7de0: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7df0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7e00: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
7e10: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
7e20: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7e30: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
7e40: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
7e50: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
7e60: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
7e70: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
7e80: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
7e90: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
7ea0: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
7eb0: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
7ec0: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7ed0: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7ee0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7ef0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7f00: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
7f10: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
7f20: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
7f30: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
7f40: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
7f50: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
7f60: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
7f70: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
7f80: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
7f90: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
7fa0: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
7fb0: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
7fc0: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
7fd0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7fe0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7ff0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
8000: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8010: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
8020: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8030: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
8040: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8050: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
8060: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8070: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
8080: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8090: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
80a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
80b0: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
80c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
80d0: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
80e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
80f0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
8100: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
8110: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
8120: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8130: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
8140: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
8150: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8160: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
8170: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
8180: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
8190: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
81a0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
81b0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
81c0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
81d0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
81e0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
81f0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
8200: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
8210: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
8220: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
8230: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
8240: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
8250: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8260: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
8270: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
8280: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
8290: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
82a0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
82b0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
82c0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
82d0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
82e0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
82f0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
8300: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
8310: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
8320: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
8330: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
8340: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
8350: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
8360: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
8370: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
8380: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
8390: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
83a0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
83b0: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
83c0: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
83d0: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
83e0: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
83f0: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
8400: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
8410: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
8420: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
8430: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
8440: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
8450: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
8460: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
8470: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
8480: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
8490: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
84a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
84b0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
84c0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
84d0: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
84e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
84f0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
8500: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
8510: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8520: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
8530: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
8540: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8550: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8560: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
8570: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8580: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
8590: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
85a0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
85b0: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
85c0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
85d0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
85e0: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
85f0: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
8600: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
8610: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
8620: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
8630: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8640: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
8650: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
8660: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
8670: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
8680: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8690: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
86a0: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
86b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
86c0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
86d0: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
86e0: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
86f0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
8700: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
8710: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
8720: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
8730: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
8740: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
8750: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
8760: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8770: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8780: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
8790: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
87a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
87b0: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
87c0: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
87d0: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
87e0: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
87f0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
8800: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
8810: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
8820: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
8830: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8840: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
8850: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8860: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
8870: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8880: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8890: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e  ersion 2 */.  in
88a0: 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69  t (*xFetch)(sqli
88b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
88c0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
88d0: 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a  int iAmt, void *
88e0: 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  *pp);.  int (*xU
88f0: 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  nfetch)(sqlite3_
8900: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8910: 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64  nt64 iOfst, void
8920: 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f   *p);.  /* Metho
8930: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8940: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  id for version 3
8950: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
8960: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
8970: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
8980: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
8990: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
89a0: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
89b0: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
89c0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
89d0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
89e0: 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72  des} {file contr
89f0: 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a  ol opcode}.**.**
8a00: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
8a10: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
8a20: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
8a30: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8a40: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
8a50: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8a60: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
8a70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8a80: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
8a90: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
8aa0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8ab0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
8ac0: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
8ad0: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
8ae0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
8af0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
8b00: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
8b10: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
8b20: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
8b30: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
8b40: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
8b50: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
8b60: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
8b70: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
8b80: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
8b90: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
8ba0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
8bb0: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
8bc0: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
8bd0: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
8be0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
8bf0: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
8c00: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
8c10: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
8c20: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
8c30: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
8c40: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
8c50: 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ..** <ul>.** <li
8c60: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8c70: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54  SIZE_HINT]].** T
8c80: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8c90: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
8ca0: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
8cb0: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
8cc0: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
8cd0: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
8ce0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
8cf0: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
8d00: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
8d10: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
8d20: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
8d30: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
8d40: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
8d50: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
8d60: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
8d70: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
8d80: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
8d90: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
8da0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
8db0: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
8dc0: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
8dd0: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
8de0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
8df0: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
8e00: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  r..**.** <li>[[S
8e10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8e20: 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  K_SIZE]].** The 
8e30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
8e40: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
8e50: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
8e60: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
8e70: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
8e80: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
8e90: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
8ea0: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
8eb0: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
8ec0: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
8ed0: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
8ee0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8ef0: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
8f00: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
8f10: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
8f20: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
8f30: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
8f40: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
8f50: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
8f60: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
8f70: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
8f80: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
8f90: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
8fa0: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
8fb0: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
8fc0: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
8fd0: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
8fe0: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
8ff0: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
9000: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9010: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9020: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
9030: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9040: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
9050: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
9060: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
9070: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9080: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
9090: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
90a0: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
90b0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
90c0: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
90d0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
90e0: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
90f0: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
9100: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
9110: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9120: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
9130: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20  OMITTED]].** No 
9140: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a  longer in use..*
9150: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9160: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a  E_FCNTL_SYNC]].*
9170: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9180: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65  NTL_SYNC] opcode
9190: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
91a0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
91b0: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74  te and.** sent t
91c0: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69  o the VFS immedi
91d0: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65  ately before the
91e0: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
91f0: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a   invoked on a.**
9200: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64   database file d
9210: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69  escriptor. Or, i
9220: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9230: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  od is not invoke
9240: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68  d .** because th
9250: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69  e user has confi
9260: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74  gured SQLite wit
9270: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79  h .** [PRAGMA sy
9280: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
9290: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
92a0: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  FF] it is invoke
92b0: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f  d in place .** o
92c0: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
92d0: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65  od. In most case
92e0: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61  s, the pointer a
92f0: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77  rgument passed w
9300: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65  ith.** this file
9310: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c  -control is NULL
9320: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68  . However, if th
9330: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9340: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a  is being synced.
9350: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20  ** as part of a 
9360: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63  multi-database c
9370: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d  ommit, the argum
9380: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
9390: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
93a0: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
93b0: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74  ing the transact
93c0: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72  ions master-jour
93d0: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56  nal file name. V
93e0: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f  FSes that .** do
93f0: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
9400: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c  ignal should sil
9410: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9420: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9430: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c  ations .** shoul
9440: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
9450: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9460: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
9470: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
9480: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74   may .** disrupt
9490: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
94a0: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
94b0: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
94c0: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
94d0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
94e0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
94f0: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20  ASETWO]].** The 
9500: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
9510: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f  MMIT_PHASETWO] o
9520: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
9530: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9540: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73   SQLite.** and s
9550: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61  ent to the VFS a
9560: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  fter a transacti
9570: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d  on has been comm
9580: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  itted immediatel
9590: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20  y.** but before 
95a0: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
95b0: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20  unlocked. VFSes 
95c0: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64  that do not need
95d0: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20   this signal.** 
95e0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
95f0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
9600: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
9610: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
9620: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9630: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
9640: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
9650: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
9660: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70  srupt the .** op
9670: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
9680: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
9690: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
96a0: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
96b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
96c0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
96d0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
96e0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
96f0: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
9700: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
9710: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
9720: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
9730: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
9740: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
9750: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
9760: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
9770: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
9780: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
9790: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
97a0: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
97b0: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
97c0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
97d0: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
97e0: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
97f0: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
9800: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
9810: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
9820: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
9830: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
9840: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
9850: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
9860: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
9870: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
9880: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
9890: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
98a0: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
98b0: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
98c0: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
98d0: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
98e0: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
98f0: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
9900: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
9910: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
9920: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
9930: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
9940: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
9950: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
9960: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
9970: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
9980: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
9990: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
99a0: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
99b0: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
99c0: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65  st integer i the
99d0: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74   new retry count
99e0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a   and the second.
99f0: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  ** integer is th
9a00: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74  e delay.  If eit
9a10: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e  her integer is n
9a20: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
9a30: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20  e setting.** is 
9a40: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20  not changed but 
9a50: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f  instead the prio
9a60: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  r value of that 
9a70: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74  setting is writt
9a80: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61  en.** into the a
9a90: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f  rray entry, allo
9aa0: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74  wing the current
9ab0: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20   retry settings 
9ac0: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f  to be.** interro
9ad0: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e  gated.  The zDbN
9ae0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
9af0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
9b00: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9b10: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d  TL_PERSIST_WAL]]
9b20: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9b30: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9b40: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  AL] opcode is us
9b50: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
9b60: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
9b70: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74  tent [WAL | Writ
9b80: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74  e Ahead Log] set
9b90: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c  ting.  By defaul
9ba0: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79  t, the auxiliary
9bb0: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20  .** write ahead 
9bc0: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d  log and shared m
9bd0: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64  emory files used
9be0: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e   for transaction
9bf0: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20   control.** are 
9c00: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
9c10: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c  leted when the l
9c20: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e  atest connection
9c30: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
9c40: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74  .** closes.  Set
9c50: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20  ting persistent 
9c60: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20  WAL mode causes 
9c70: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70  those files to p
9c80: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20  ersist after.** 
9c90: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69  close.  Persisti
9ca0: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20  ng the files is 
9cb0: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65  useful when othe
9cc0: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74  r processes that
9cd0: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20   do not.** have 
9ce0: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e  write permission
9cf0: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72   on the director
9d00: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  y containing the
9d10: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
9d20: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74  ant.** to read t
9d30: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9d40: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64  , as the WAL and
9d50: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
9d60: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a  iles must exist.
9d70: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20  ** in order for 
9d80: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20  the database to 
9d90: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  be readable.  Th
9da0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
9db0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
9dc0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9dd0: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
9de0: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
9df0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
9e00: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
9e10: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
9e20: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20  able persistent 
9e30: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  WAL mode or 1 to
9e40: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65   enable persiste
9e50: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20  nt.** WAL mode. 
9e60: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
9e70: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
9e80: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
9e90: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
9ea0: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63  * WAL persistenc
9eb0: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
9ec0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9ed0: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
9ee0: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
9ef0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9f00: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
9f10: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ITE] opcode is u
9f20: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
9f30: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
9f40: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65  stent "powersafe
9f50: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22  -overwrite" or "
9f60: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20  PSOW" setting.  
9f70: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67  The PSOW setting
9f80: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74  .** determines t
9f90: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  he [SQLITE_IOCAP
9fa0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
9fb0: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65  RITE] bit of the
9fc0: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61  .** xDeviceChara
9fd0: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
9fe0: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70  ds. The fourth p
9ff0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
a000: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a010: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
a020: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
a030: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
a040: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
a050: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
a060: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d  to disable zero-
a070: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31  damage mode or 1
a080: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d   to enable zero-
a090: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20  damage.** mode. 
a0a0: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
a0b0: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
a0c0: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
a0d0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
a0e0: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  * zero-damage mo
a0f0: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  de setting..**.*
a100: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a110: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d  CNTL_OVERWRITE]]
a120: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a130: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
a140: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f  ] opcode is invo
a150: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66  ked by SQLite af
a160: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61  ter opening.** a
a170: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
a180: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  on to indicate t
a190: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69  hat, unless it i
a1a0: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f  s rolled back fo
a1b0: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e  r some.** reason
a1c0: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74  , the entire dat
a1d0: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
a1e0: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  be overwritten b
a1f0: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a  y the current .*
a200: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54  * transaction. T
a210: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56  his is used by V
a220: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73  ACUUM operations
a230: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a240: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
a250: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ME]].** ^The [SQ
a260: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
a270: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  ME] opcode can b
a280: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
a290: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a   the names of.**
a2a0: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20   all [VFSes] in 
a2b0: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20  the VFS stack.  
a2c0: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66  The names are of
a2d0: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61   all VFS shims a
a2e0: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  nd the.** final 
a2f0: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53  bottom-level VFS
a300: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74   are written int
a310: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
a320: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
a330: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
a340: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  d the result is 
a350: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68  stored in the ch
a360: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  ar* variable.** 
a370: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20  that the fourth 
a380: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71  parameter of [sq
a390: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a3a0: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e  ol()] points to.
a3b0: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69  .** The caller i
a3c0: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
a3d0: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65  r freeing the me
a3e0: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20  mory when done. 
a3f0: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20   As with.** all 
a400: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74  file-control act
a410: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e  ions, there is n
a420: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  o guarantee that
a430: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61   this will actua
a440: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69  lly.** do anythi
a450: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f  ng.  Callers sho
a460: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74  uld initialize t
a470: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a480: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e to a NULL.** p
a490: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74  ointer in case t
a4a0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a4b0: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
a4c0: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d  ted.  This file-
a4d0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e  control.** is in
a4e0: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e  tended for diagn
a4f0: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a  ostic use only..
a500: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a510: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a520: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
a530: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
a540: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
a550: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
a560: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
a570: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
a580: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
a590: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
a5a0: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
a5b0: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
a5c0: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
a5d0: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
a5e0: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
a5f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
a600: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
a610: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
a620: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
a630: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
a640: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
a650: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
a660: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
a670: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
a680: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
a690: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
a6a0: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
a6b0: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
a6c0: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
a6d0: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
a6e0: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
a6f0: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
a700: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
a710: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
a720: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a730: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
a740: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
a750: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
a760: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
a770: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
a780: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
a790: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
a7a0: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
a7b0: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
a7c0: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
a7d0: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
a7e0: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
a7f0: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
a800: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
a810: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
a820: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
a830: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a840: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a850: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
a860: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
a870: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
a880: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
a890: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
a8a0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a8b0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
a8c0: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
a8d0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
a8e0: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
a8f0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
a900: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
a910: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
a920: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
a930: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
a940: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
a950: 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49  d statement.  ^I
a960: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
a970: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a980: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
a990: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63  .** any result c
a9a0: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ode other than [
a9b0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53  SQLITE_OK] or [S
a9c0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a9d0: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
a9e0: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f  hat the VFS enco
a9f0: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72  untered an error
aa00: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20   while handling 
aa10: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64  the [PRAGMA] and
aa20: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74   the.** compilat
aa30: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d  ion of the PRAGM
aa40: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  A fails with an 
aa50: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51  error.  ^The [SQ
aa60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
aa70: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
aa80: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65  ol occurs at the
aa90: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72   beginning of pr
aaa0: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61  agma statement a
aab0: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a  nalysis and so.*
aac0: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20  * it is able to 
aad0: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69  override built-i
aae0: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  n [PRAGMA] state
aaf0: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ments..**.** <li
ab00: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
ab10: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a  BUSYHANDLER]].**
ab20: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
ab30: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
ab40: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
ab50: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
ab60: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
ab70: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
ab80: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
ab90: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
aba0: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
abb0: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
abc0: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
abd0: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
abe0: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
abf0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
ac00: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
ac10: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
ac20: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
ac30: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
ac40: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
ac50: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
ac60: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
ac70: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
ac80: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
ac90: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
aca0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
acb0: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
acc0: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
acd0: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
ace0: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
acf0: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
ad00: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
ad10: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
ad20: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
ad30: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
ad40: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
ad50: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
ad60: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
ad70: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
ad80: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
ad90: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
ada0: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
adb0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
adc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
add0: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20  MPFILENAME]].** 
ade0: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e  ^Application can
adf0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c   invoke the [SQL
ae00: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
ae10: 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e  LENAME] file-con
ae20: 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20  trol.** to have 
ae30: 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20  SQLite generate 
ae40: 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  a.** temporary f
ae50: 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68  ilename using th
ae60: 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
ae70: 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65   that is followe
ae80: 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a  d to generate.**
ae90: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
aea0: 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61  ames for TEMP ta
aeb0: 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69  bles and other i
aec0: 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54  nternal uses.  T
aed0: 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  he.** argument s
aee0: 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a  hould be a char*
aef0: 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20  * which will be 
af00: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
af10: 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74  filename.** writ
af20: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
af30: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
af40: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
af50: 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68  .  The caller sh
af60: 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b  ould.** invoke [
af70: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
af80: 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f  on the result to
af90: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
afa0: 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  leak..**.** <li>
afb0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  [[SQLITE_FCNTL_M
afc0: 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  MAP_SIZE]].** Th
afd0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
afe0: 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
aff0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b000: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20  to query or set 
b010: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e  the.** maximum n
b020: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74  umber of bytes t
b030: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64  hat will be used
b040: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70   for memory-mapp
b050: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61  ed I/O..** The a
b060: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
b070: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20  nter to a value 
b080: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f  of type sqlite3_
b090: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73  int64 that.** is
b0a0: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78   an advisory max
b0b0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b0c0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
b0d0: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20   to memory map. 
b0e0: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   The.** pointer 
b0f0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
b100: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75  ith the old valu
b110: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73  e.  The limit is
b120: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a   not changed if.
b130: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69  ** the value ori
b140: 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20  ginally pointed 
b150: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  to is negative, 
b160: 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65  and so the curre
b170: 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e  nt limit .** can
b180: 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70   be queried by p
b190: 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e  assing in a poin
b1a0: 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76  ter to a negativ
b1b0: 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a  e number.  This.
b1c0: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
b1d0: 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
b1e0: 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ly to implement 
b1f0: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
b200: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  e]..**.** <li>[[
b210: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b220: 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  CE]].** The [SQL
b230: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b240: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72   file control pr
b250: 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20  ovides advisory 
b260: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74  information.** t
b270: 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20  o the VFS about 
b280: 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20  what the higher 
b290: 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51  layers of the SQ
b2a0: 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64  Lite stack are d
b2b0: 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69  oing..** This fi
b2c0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
b2d0: 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61  ed by some VFS a
b2e0: 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20  ctivity tracing 
b2f0: 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20  [shims]..** The 
b300: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65  argument is a ze
b310: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
b320: 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61  ring.  Higher la
b330: 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53  yers in the.** S
b340: 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20  QLite stack may 
b350: 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63  generate instanc
b360: 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  es of this file 
b370: 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68  control if.** th
b380: 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43  e [SQLITE_USE_FC
b390: 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69  NTL_TRACE] compi
b3a0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
b3b0: 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
b3c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b3d0: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a  NTL_HAS_MOVED]].
b3e0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b3f0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20  CNTL_HAS_MOVED] 
b400: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74  file control int
b410: 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75  erprets its argu
b420: 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69  ment as a.** poi
b430: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
b440: 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73  er and it writes
b450: 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20   a boolean into 
b460: 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70  that integer dep
b470: 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65  ending.** on whe
b480: 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
b490: 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65  file has been re
b4a0: 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72  named, moved, or
b4b0: 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69   deleted since i
b4c0: 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f  t.** was first o
b4d0: 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  pened..**.** <li
b4e0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b4f0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
b500: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b510: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
b520: 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65  T_HANDLE] opcode
b530: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
b540: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
b550: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
b560: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
b570: 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74  method to swap t
b580: 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77  he file handle w
b590: 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70  ith the one.** p
b5a0: 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
b5b0: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20   pArg argument. 
b5c0: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
b5d0: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
b5e0: 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f  testing.** and o
b5f0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
b600: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
b610: 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65  QLITE_TEST is de
b620: 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  fined..**.** <li
b630: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b640: 5a 49 50 56 46 53 5f 50 41 47 45 52 5d 5d 0a 2a  ZIPVFS_PAGER]].*
b650: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b660: 4e 54 4c 5f 5a 49 50 56 46 53 5f 50 41 47 45 52  NTL_ZIPVFS_PAGER
b670: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
b680: 20 62 79 20 74 68 65 20 4f 54 41 20 65 78 74 65   by the OTA exte
b690: 6e 73 69 6f 6e 20 77 68 65 6e 0a 2a 2a 20 75 70  nsion when.** up
b6a0: 64 61 74 69 6e 67 20 61 20 7a 69 70 76 66 73 20  dating a zipvfs 
b6b0: 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20  database..**.** 
b6c0: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
b6d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
b6e0: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
b6f0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
b700: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
b710: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20  ROXYFILE        
b720: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
b730: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52  QLITE_SET_LOCKPR
b740: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20  OXYFILE         
b750: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
b760: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
b770: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b780: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
b790: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
b7a0: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
b7b0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
b7c0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
b7d0: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
b7e0: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
b7f0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
b800: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
b810: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
b820: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
b830: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
b840: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b850: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
b860: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
b870: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b880: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
b890: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
b8a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b8b0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
b8c0: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
b8d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b8e0: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
b8f0: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
b900: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b910: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
b920: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
b930: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b940: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
b950: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
b960: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b970: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
b980: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
b990: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
b9a0: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
b9b0: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
b9c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
b9d0: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
b9e0: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
b9f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
ba00: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
ba10: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
ba20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
ba30: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
ba40: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
ba50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
ba60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
ba70: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
ba80: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
ba90: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
baa0: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
bab0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
bac0: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
bad0: 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  23.#define SQLIT
bae0: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5f 50  E_FCNTL_ZIPVFS_P
baf0: 41 47 45 52 20 20 20 20 20 20 20 20 20 20 20 32  AGER           2
bb00: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
bb10: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
bb20: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
bb30: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
bb40: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
bb50: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
bb60: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
bb70: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
bb80: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
bb90: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
bba0: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
bbb0: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
bbc0: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
bbd0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
bbe0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
bbf0: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
bc00: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
bc10: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
bc20: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
bc30: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
bc40: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
bc50: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
bc60: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
bc70: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
bc80: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
bc90: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
bca0: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
bcb0: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
bcc0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
bcd0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
bce0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
bcf0: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
bd00: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
bd10: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
bd20: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
bd30: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
bd40: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
bd50: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
bd60: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
bd70: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a  system".  See.**
bd80: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20   the [VFS | VFS 
bd90: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
bda0: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72  or further infor
bdb0: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
bdc0: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
bdd0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
bde0: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
bdf0: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
be00: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
be10: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
be20: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
be30: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
be40: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
be50: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
be60: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
be70: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
be80: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
be90: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
bea0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
beb0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
bec0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
bed0: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
bee0: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
bef0: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
bf00: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
bf10: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
bf20: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
bf30: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
bf40: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
bf50: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
bf60: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
bf70: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
bf80: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
bf90: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
bfa0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
bfb0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
bfc0: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
bfd0: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
bfe0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
bff0: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
c000: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
c010: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
c020: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
c030: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
c040: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
c050: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
c060: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
c070: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
c080: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
c090: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
c0a0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
c0b0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
c0c0: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
c0d0: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
c0e0: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
c0f0: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
c100: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
c110: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
c120: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
c130: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
c140: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
c150: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
c160: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
c170: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
c180: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
c190: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
c1a0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
c1b0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
c1c0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
c1d0: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
c1e0: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
c1f0: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
c200: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
c210: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
c220: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
c230: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
c240: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
c250: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
c260: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
c270: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
c280: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
c290: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
c2a0: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
c2b0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
c2c0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
c2d0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  les..**.** [[sql
c2e0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d  ite3_vfs.xOpen]]
c2f0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
c300: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
c310: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
c320: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
c330: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
c340: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
c350: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
c360: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
c370: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69  e() with an opti
c380: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65  onal suffix adde
c390: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66  d..** ^If a suff
c3a0: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74  ix is added to t
c3b0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
c3c0: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a  ameter, it will.
c3d0: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20  ** consist of a 
c3e0: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61  single "-" chara
c3f0: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79  cter followed by
c400: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a   no more than.**
c410: 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   11 alphanumeric
c420: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72   and/or "-" char
c430: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69  acters..** ^SQLi
c440: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
c450: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
c460: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
c470: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
c480: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
c490: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
c4a0: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
c4b0: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
c4c0: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
c4d0: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
c4e0: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
c4f0: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
c500: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
c510: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
c520: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
c530: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
c540: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
c550: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
c560: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
c570: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
c580: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
c590: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
c5a0: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
c5b0: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72  file.  ^Whenever
c5c0: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
c5d0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
c5e0: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
c5f0: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
c600: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
c610: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
c620: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
c630: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
c640: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
c650: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
c660: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
c670: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
c680: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
c690: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
c6a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
c6b0: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
c6c0: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
c6d0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
c6e0: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
c6f0: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
c700: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
c710: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
c720: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
c730: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
c740: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
c750: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
c760: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
c770: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
c780: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
c790: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
c7a0: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
c7b0: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
c7c0: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  t..**.** ^(SQLit
c7d0: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
c7e0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
c7f0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
c800: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
c810: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
c820: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
c830: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
c840: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
c850: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
c860: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
c870: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
c880: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
c890: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
c8a0: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
c8b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
c8c0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
c8d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c8e0: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
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 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
c910: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
c920: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
c930: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
c940: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d  SQLITE_OPEN_WAL]
c950: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
c960: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
c970: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
c980: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
c990: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
c9a0: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
c9b0: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
c9c0: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
c9d0: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
c9e0: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
c9f0: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
ca00: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
ca10: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
ca20: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
ca30: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
ca40: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
ca50: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
ca60: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
ca70: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
ca80: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
ca90: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
caa0: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
cab0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
cac0: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
cad0: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
cae0: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
caf0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
cb00: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
cb10: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
cb20: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
cb30: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
cb40: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
cb50: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
cb60: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
cb70: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
cb80: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
cb90: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
cba0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
cbb0: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
cbc0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
cbd0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
cbe0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
cbf0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
cc00: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
cc10: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
cc20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
cc30: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
cc40: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
cc50: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
cc60: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
cc70: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c  osed.  ^The [SQL
cc80: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
cc90: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
cca0: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
ccb0: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68  databases and th
ccc0: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72  eir journals, tr
ccd0: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62  ansient.** datab
cce0: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75  ases, and subjou
ccf0: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rnals..**.** ^Th
cd00: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
cd10: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
cd20: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
cd30: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
cd40: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
cd50: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
cd60: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
cd70: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
cd80: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
cd90: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
cda0: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
cdb0: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
cdc0: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
cdd0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
cde0: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
cdf0: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
ce00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
ce10: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
ce20: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
ce30: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
ce40: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
ce50: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
ce60: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
ce70: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
ce80: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
ce90: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
cea0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
ceb0: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
cec0: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
ced0: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c  ess..**.** ^At l
cee0: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
cef0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
cf00: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
cf10: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
cf20: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
cf30: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
cf40: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
cf50: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
cf60: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
cf70: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
cf80: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
cf90: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
cfa0: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
cfb0: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
cfc0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
cfd0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
cfe0: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
cff0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
d000: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
d010: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
d020: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
d030: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
d040: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
d050: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
d060: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
d070: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
d080: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
d090: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
d0a0: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
d0b0: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
d0c0: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
d0d0: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
d0e0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
d0f0: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
d100: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73   call..**.** [[s
d110: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65  qlite3_vfs.xAcce
d120: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ss]].** ^The fla
d130: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
d140: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
d150: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
d160: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
d170: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
d180: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
d190: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
d1a0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
d1b0: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
d1c0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
d1d0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
d1e0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
d1f0: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
d200: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
d210: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
d220: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
d230: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
d240: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
d250: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
d260: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
d270: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
d280: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
d290: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
d2a0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
d2b0: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
d2c0: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
d2d0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
d2e0: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
d2f0: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
d300: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
d310: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
d320: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
d330: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
d340: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
d350: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
d360: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
d370: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
d380: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
d390: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
d3a0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
d3b0: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
d3c0: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
d3d0: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
d3e0: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
d3f0: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
d400: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
d410: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
d420: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
d430: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
d440: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
d450: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
d460: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
d470: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
d480: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
d490: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
d4a0: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
d4b0: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
d4c0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
d4d0: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
d4e0: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
d4f0: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
d500: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
d510: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
d520: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
d530: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
d540: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
d550: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
d560: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
d570: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
d580: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
d590: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
d5a0: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
d5b0: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
d5c0: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
d5d0: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
d5e0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
d5f0: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
d600: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
d610: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
d620: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
d630: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
d640: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
d650: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
d660: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
d670: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
d680: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
d690: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
d6a0: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
d6b0: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30  lied by 86400000
d6c0: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
d6d0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
d6e0: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
d6f0: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
d700: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
d710: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
d720: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
d730: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
d740: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
d750: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
d760: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
d770: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
d780: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
d790: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
d7a0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
d7b0: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
d7c0: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
d7d0: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
d7e0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
d7f0: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
d800: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
d810: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
d820: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
d830: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
d840: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
d850: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
d860: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
d870: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
d880: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
d890: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
d8a0: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
d8b0: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
d8c0: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
d8d0: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
d8e0: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
d8f0: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
d900: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
d910: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
d920: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
d930: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
d940: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
d950: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
d960: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
d970: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
d980: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
d990: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
d9a0: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
d9b0: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
d9c0: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
d9d0: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
d9e0: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
d9f0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
da00: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
da10: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
da20: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
da30: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
da40: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
da50: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
da60: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
da70: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
da80: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
da90: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
daa0: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
dab0: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
dac0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
dad0: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
dae0: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
daf0: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
db00: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
db10: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
db20: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
db30: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
db40: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
db50: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
db60: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
db70: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
db80: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
db90: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
dba0: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
dbb0: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
dbc0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
dbd0: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
dbe0: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
dbf0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
dc00: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
dc10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
dc20: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
dc30: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
dc40: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
dc50: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
dc60: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
dc70: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
dc80: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
dc90: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
dca0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
dcb0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
dcc0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
dcd0: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
dce0: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
dcf0: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
dd00: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
dd10: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
dd20: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
dd30: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
dd40: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
dd50: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
dd60: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
dd70: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
dd80: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
dd90: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
dda0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ddb0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
ddc0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
ddd0: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
dde0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ddf0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
de00: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
de10: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
de20: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
de30: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
de40: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
de50: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
de60: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
de70: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
de80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
de90: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
dea0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
deb0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
dec0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
ded0: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
dee0: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
def0: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
df00: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
df10: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
df20: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
df30: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
df40: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
df50: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
df60: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
df70: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
df80: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
df90: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
dfa0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
dfb0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
dfc0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
dfd0: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
dfe0: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
dff0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
e000: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
e010: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
e020: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
e030: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
e040: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
e050: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
e060: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
e070: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
e080: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
e090: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
e0a0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
e0b0: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
e0c0: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
e0d0: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
e0e0: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
e0f0: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
e100: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
e110: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
e120: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
e130: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
e140: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
e150: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
e160: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
e170: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
e180: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e190: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
e1a0: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
e1b0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
e1c0: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
e1d0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e1e0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e1f0: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
e200: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
e210: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
e220: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e230: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
e240: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
e250: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
e260: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
e270: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
e280: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
e290: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
e2a0: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
e2b0: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
e2c0: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
e2d0: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
e2e0: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
e2f0: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
e300: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
e310: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
e320: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
e330: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
e340: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
e350: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
e360: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
e370: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
e380: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e390: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
e3a0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
e3b0: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
e3c0: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
e3d0: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
e3e0: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
e3f0: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
e400: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
e410: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
e420: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
e430: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
e440: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
e450: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
e460: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e470: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
e480: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
e490: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
e4a0: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
e4b0: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
e4c0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
e4d0: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
e4e0: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
e4f0: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
e500: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
e510: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
e520: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
e530: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
e540: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
e550: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
e560: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
e570: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
e580: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
e590: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
e5a0: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
e5b0: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
e5c0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
e5d0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
e5e0: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
e5f0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
e600: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
e610: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
e620: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
e630: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
e640: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
e650: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
e660: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
e670: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
e680: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
e690: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
e6a0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
e6b0: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
e6c0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
e6d0: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
e6e0: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
e6f0: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
e700: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
e710: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
e720: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
e730: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
e740: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
e750: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
e760: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
e770: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
e780: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
e790: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
e7a0: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
e7b0: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
e7c0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
e7d0: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
e7e0: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
e7f0: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
e800: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
e810: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
e820: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
e830: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
e840: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
e850: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
e860: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
e870: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
e880: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
e890: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
e8a0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
e8b0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
e8c0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
e8d0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
e8e0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
e8f0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
e900: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
e910: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
e920: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
e930: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
e940: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
e950: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
e960: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20  ** was given on 
e970: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
e980: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
e990: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
e9a0: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
e9b0: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
e9c0: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
e9d0: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
e9e0: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
e9f0: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
ea00: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
ea10: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
ea20: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
ea30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
ea40: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
ea50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ea60: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
ea70: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
ea80: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
ea90: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
eaa0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
eab0: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
eac0: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
ead0: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
eae0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
eaf0: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
eb00: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
eb10: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
eb20: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
eb30: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
eb40: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
eb50: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
eb60: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
eb70: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
eb80: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
eb90: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
eba0: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
ebb0: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
ebc0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
ebd0: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
ebe0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
ebf0: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
ec00: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
ec10: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
ec20: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
ec30: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
ec40: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
ec50: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
ec60: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ec70: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
ec80: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
ec90: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
eca0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
ecb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ecc0: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
ecd0: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
ece0: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
ecf0: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
ed00: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
ed10: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
ed20: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
ed30: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
ed40: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
ed50: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
ed60: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
ed70: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
ed80: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
ed90: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
eda0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
edb0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
edc0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
edd0: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
ede0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
edf0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
ee00: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
ee10: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
ee20: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
ee30: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
ee40: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
ee50: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
ee60: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
ee70: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
ee80: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
ee90: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
eea0: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
eeb0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
eec0: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
eed0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
eee0: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
eef0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
ef00: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
ef10: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
ef20: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
ef30: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
ef40: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
ef50: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
ef60: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ef70: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
ef80: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
ef90: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
efa0: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
efb0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
efc0: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
efd0: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
efe0: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
eff0: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
f000: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
f010: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
f020: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
f030: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
f040: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
f050: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
f060: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
f070: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
f080: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
f090: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
f0a0: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
f0b0: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
f0c0: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
f0d0: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
f0e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f0f0: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
f100: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
f110: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
f120: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
f130: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
f140: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
f150: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f160: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
f170: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
f180: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f190: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
f1a0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
f1b0: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
f1c0: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
f1d0: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
f1e0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
f1f0: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
f200: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f210: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
f220: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
f230: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
f240: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
f250: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
f260: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
f270: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
f280: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
f290: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
f2a0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
f2b0: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
f2c0: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
f2d0: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
f2e0: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
f2f0: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
f300: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
f310: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
f320: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
f330: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
f340: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
f350: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
f360: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
f370: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
f380: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
f390: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
f3a0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
f3b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
f3c0: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
f3d0: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
f3e0: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
f3f0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f400: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
f410: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
f420: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
f430: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
f440: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
f450: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
f460: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
f470: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
f480: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
f490: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
f4a0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
f4b0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
f4c0: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
f4d0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
f4e0: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
f4f0: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
f500: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f510: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
f520: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
f530: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
f540: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f550: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
f560: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
f570: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
f580: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
f590: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
f5a0: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
f5b0: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
f5c0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
f5d0: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
f5e0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
f5f0: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
f600: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
f610: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
f620: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
f630: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
f640: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
f650: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
f660: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
f670: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
f680: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
f690: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
f6a0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
f6b0: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
f6c0: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
f6d0: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
f6e0: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
f6f0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
f700: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
f710: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
f720: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
f730: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
f740: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
f750: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
f760: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
f770: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
f780: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
f790: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
f7a0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
f7b0: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
f7c0: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
f7d0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
f7e0: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
f7f0: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
f800: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
f810: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
f820: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
f830: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
f840: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
f850: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
f860: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
f870: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
f880: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
f890: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
f8a0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
f8b0: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
f8c0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
f8d0: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
f8e0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f8f0: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
f900: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
f910: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
f920: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
f930: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
f940: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
f950: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
f960: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
f970: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
f980: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
f990: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
f9a0: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
f9b0: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
f9c0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
f9d0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
f9e0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f9f0: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
fa00: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
fa10: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
fa20: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
fa30: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
fa40: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
fa50: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
fa60: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
fa70: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
fa80: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
fa90: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
faa0: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
fab0: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
fac0: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
fad0: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
fae0: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
faf0: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
fb00: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
fb10: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
fb20: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
fb30: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
fb40: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
fb50: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
fb60: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
fb70: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
fb80: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
fb90: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
fba0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
fbb0: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
fbc0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
fbd0: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
fbe0: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
fbf0: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
fc00: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
fc10: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
fc20: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
fc30: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
fc40: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
fc50: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
fc60: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
fc70: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
fc80: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
fc90: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
fca0: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
fcb0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
fcc0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
fcd0: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
fce0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
fcf0: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
fd00: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
fd10: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
fd20: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
fd30: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
fd40: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
fd50: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
fd60: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
fd70: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
fd80: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
fd90: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
fda0: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
fdb0: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
fdc0: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
fdd0: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
fde0: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
fdf0: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
fe00: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
fe10: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
fe20: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
fe30: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
fe40: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
fe50: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
fe60: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
fe70: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
fe80: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
fe90: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
fea0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
feb0: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
fec0: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
fed0: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
fee0: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
fef0: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
ff00: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
ff10: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
ff20: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
ff30: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
ff40: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
ff50: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
ff60: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ff70: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
ff80: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
ff90: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
ffa0: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
ffb0: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
ffc0: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
ffd0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
ffe0: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
fff0: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
10000 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
10010 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
10020 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
10030 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
10040 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
10050 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
10060 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
10070 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
10080 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10090 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
100a0 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
100b0 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
100c0 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
100d0 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
100e0 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
100f0 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
10100 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
10110 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
10120 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
10130 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
10140 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
10150 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
10160 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
10170 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
10180 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
10190 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
101a0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
101b0 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
101c0 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
101d0 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
101e0 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
101f0 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
10200 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
10210 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
10220 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
10230 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
10240 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
10250 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
10260 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10270 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ions.**.** The s
10280 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10290 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
102a0 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
102b0 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
102c0 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
102d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
102e0 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
102f0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
10300 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10310 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
10320 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
10330 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
10340 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
10350 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
10360 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
10370 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
10380 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
10390 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
103a0 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
103b0 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
103c0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
103d0 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
103e0 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
103f0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
10400 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
10410 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
10420 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
10430 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
10440 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
10450 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
10460 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
10470 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
10480 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
10490 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
104a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
104b0 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
104c0 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
104d0 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
104e0 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
104f0 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
10500 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
10510 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
10520 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
10530 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10540 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
10550 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
10560 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
10570 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
10580 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
10590 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
105a0 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
105b0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
105c0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
105d0 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
105e0 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
105f0 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
10600 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10610 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
10620 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
10630 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
10640 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
10650 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
10660 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
10670 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10680 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
10690 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
106a0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
106b0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
106c0 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
106d0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
106e0 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
106f0 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
10700 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10710 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
10720 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
10730 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
10740 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
10750 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
10760 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
10770 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10780 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
10790 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
107a0 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
107b0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
107c0 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
107d0 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
107e0 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
107f0 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
10800 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
10810 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
10820 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
10830 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
10840 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
10850 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
10860 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
10870 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
10880 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
10890 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
108a0 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
108b0 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
108c0 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
108d0 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
108e0 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
108f0 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
10900 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
10910 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
10920 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
10930 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
10940 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
10950 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
10960 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
10970 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
10980 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
10990 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
109a0 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
109b0 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
109c0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
109d0 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
109e0 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
109f0 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
10a00 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
10a10 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
10a20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
10a30 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
10a40 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
10a50 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
10a60 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
10a70 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
10a80 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
10a90 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
10aa0 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
10ab0 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
10ac0 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
10ad0 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
10ae0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
10af0 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
10b00 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
10b10 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
10b20 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
10b30 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
10b40 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
10b50 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
10b60 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
10b70 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
10b80 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
10b90 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
10ba0 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
10bb0 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
10bc0 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
10bd0 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
10be0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10bf0 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
10c00 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
10c10 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
10c20 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
10c30 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
10c40 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
10c50 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
10c60 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
10c70 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
10c80 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
10c90 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
10ca0 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
10cb0 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
10cc0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
10cd0 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
10ce0 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
10cf0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
10d00 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
10d10 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
10d20 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
10d30 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
10d40 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
10d50 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
10d60 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
10d70 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
10d80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
10d90 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
10da0 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
10db0 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65  llocator.  For e
10dc0 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69  xample,.** it mi
10dd0 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79  ght allocate any
10de0 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73   require mutexes
10df0 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69   or initialize i
10e00 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20  nternal data.** 
10e10 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65  structures.  The
10e20 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
10e30 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e  d is invoked (in
10e40 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20  directly) by.** 
10e50 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
10e60 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20  n()] and should 
10e70 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  deallocate any r
10e80 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65  esources acquire
10e90 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20  d.** by xInit.  
10ea0 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69  The pAppData poi
10eb0 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20  nter is used as 
10ec0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
10ed0 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61  er to.** xInit a
10ee0 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a  nd xShutdown..**
10ef0 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73  .** SQLite holds
10f00 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
10f10 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
10f20 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20  ] mutex when it 
10f30 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78  invokes.** the x
10f40 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20  Init method, so 
10f50 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
10f60 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72   need not be thr
10f70 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a  eadsafe.  The.**
10f80 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
10f90 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64  d is only called
10fa0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
10fb0 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74  hutdown()] so it
10fc0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65   does.** not nee
10fd0 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61  d to be threadsa
10fe0 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20  fe either.  For 
10ff0 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64  all other method
11000 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c  s, SQLite.** hol
11010 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
11020 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d  UTEX_STATIC_MEM]
11030 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61   mutex as long a
11040 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
11050 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
11060 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  S] configuration
11070 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65   option is turne
11080 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69  d on (which.** i
11090 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29  t is by default)
110a0 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68   and so the meth
110b0 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69  ods are automati
110c0 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64  cally serialized
110d0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66  ..** However, if
110e0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
110f0 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69  MEMSTATUS] is di
11100 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  sabled, then the
11110 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64   other.** method
11120 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  s must be thread
11130 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b  safe or else mak
11140 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61  e their own arra
11150 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20  ngements for.** 
11160 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  serialization..*
11170 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  *.** SQLite will
11180 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49   never invoke xI
11190 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20  nit() more than 
111a0 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20  once without an 
111b0 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63  intervening.** c
111c0 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e  all to xShutdown
111d0 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
111e0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
111f0 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
11200 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
11210 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
11220 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
11230 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
11240 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
11250 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
11260 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
11270 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
11280 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
11290 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
112a0 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
112b0 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
112c0 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
112d0 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
112e0 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
112f0 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
11300 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
11310 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
11320 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
11330 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
11340 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
11350 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
11360 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
11370 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
11380 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
11390 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
113a0 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
113b0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
113c0 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
113d0 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
113e0 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
113f0 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
11400 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
11410 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
11420 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
11430 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
11440 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
11450 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
11460 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11470 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
11480 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
11490 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f  S: {configuratio
114a0 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20  n option}.**.** 
114b0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
114c0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
114d0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
114e0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
114f0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
11500 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
11510 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
11520 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
11530 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
11540 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
11550 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
11560 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
11570 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
11580 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
11590 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
115a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
115b0 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
115c0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
115d0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
115e0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
115f0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
11600 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
11610 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
11620 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
11630 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
11640 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
11650 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
11660 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
11670 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
11680 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
11690 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
116a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
116b0 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
116c0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
116d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
116e0 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  GLETHREAD]] <dt>
116f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
11700 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a  NGLETHREAD</dt>.
11710 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
11720 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
11730 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
11740 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
11750 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
11760 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67  ng mode] to Sing
11770 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  le-thread.  In o
11780 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
11790 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  isables.** all m
117a0 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73  utexing and puts
117b0 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d   SQLite into a m
117c0 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e  ode where it can
117d0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a   only be used.**
117e0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
117f0 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ead.   ^If SQLit
11800 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11810 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
11820 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
11830 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11840 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
11850 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
11860 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
11870 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  le to change the
11880 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11890 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75  ] from its defau
118a0 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53  lt.** value of S
118b0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64  ingle-thread and
118c0 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   so [sqlite3_con
118d0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
118e0 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rn .** [SQLITE_E
118f0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
11900 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
11910 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
11920 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  EAD.** configura
11930 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
11940 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11950 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
11960 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
11970 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
11980 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
11990 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
119a0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
119b0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
119c0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
119d0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
119e0 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
119f0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
11a00 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
11a10 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
11a20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11a30 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
11a40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
11a50 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
11a60 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
11a70 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
11a80 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
11a90 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
11aa0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
11ab0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11ac0 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
11ad0 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
11ae0 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
11af0 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
11b00 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
11b10 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
11b20 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
11b30 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
11b40 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
11b50 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
11b60 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
11b70 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
11b80 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
11b90 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
11ba0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
11bb0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
11bc0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
11bd0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
11be0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
11bf0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
11c00 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
11c10 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
11c20 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
11c30 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
11c40 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
11c50 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
11c60 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
11c70 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
11c80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
11c90 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
11ca0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
11cb0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11cc0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
11cd0 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ZED]] <dt>SQLITE
11ce0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
11cf0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
11d00 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
11d10 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
11d20 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
11d30 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
11d40 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11d50 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20   to Serialized. 
11d60 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11d70 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62  this option enab
11d80 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
11d90 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65  es including the
11da0 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75   recursive.** mu
11db0 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61  texes on [databa
11dc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
11dd0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
11de0 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
11df0 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65  .** In this mode
11e00 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64   (which is the d
11e10 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69  efault when SQLi
11e20 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11e30 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  ith.** [SQLITE_T
11e40 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68  HREADSAFE=1]) th
11e50 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
11e60 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72   will itself ser
11e70 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a  ialize access.**
11e80 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
11e90 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
11ea0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11eb0 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65  nts] so that the
11ec0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
11ed0 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74  is free to use t
11ee0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
11ef0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72  e connection] or
11f00 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72   the.** same [pr
11f10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11f20 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74  ] in different t
11f30 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
11f40 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20  me time..** ^If 
11f50 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11f60 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11f70 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11f80 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
11f90 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
11fa0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
11fb0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
11fc0 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
11fd0 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74  he Serialized [t
11fe0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
11ff0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
12000 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
12010 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
12020 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
12030 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
12040 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
12050 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ED configuration
12060 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
12070 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12080 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  FIG_MALLOC]] <dt
12090 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
120a0 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
120b0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
120c0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70  CONFIG_MALLOC op
120d0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
120e0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
120f0 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  ch is .** a poin
12100 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
12110 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
12120 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
12130 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
12140 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
12150 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
12160 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
12170 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12180 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
12190 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
121a0 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
121b0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
121c0 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
121d0 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d  ite.)^ ^SQLite m
121e0 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20  akes.** its own 
121f0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
12200 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
12210 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12220 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12230 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65  re.** before the
12240 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12250 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  ()] call returns
12260 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12270 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12280 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
12290 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
122a0 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
122b0 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
122c0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
122d0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
122e0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
122f0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
12300 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
12310 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
12320 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12330 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
12340 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12350 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
12360 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
12370 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
12380 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
12390 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
123a0 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
123b0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
123c0 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
123d0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
123e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
123f0 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
12400 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
12410 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
12420 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
12430 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
12440 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
12450 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64  or example. </dd
12460 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12470 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
12480 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  S]] <dt>SQLITE_C
12490 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
124a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
124b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
124c0 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e  MEMSTATUS option
124d0 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
124e0 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
124f0 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  nt,.** interpret
12500 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c  ed as a boolean,
12510 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
12520 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
12530 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20  ollection of.** 
12540 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12550 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  n statistics. ^(
12560 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
12570 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
12580 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
12590 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  d, the following
125a0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
125b0 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70  es become non-op
125c0 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
125d0 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
125e0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
125f0 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
12600 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
12610 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
12620 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
12630 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
12640 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  64()].**   <li> 
12650 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28  [sqlite3_status(
12660 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
12670 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
12680 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
12690 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
126a0 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
126b0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
126c0 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
126d0 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
126e0 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
126f0 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
12700 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12710 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
12720 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
12730 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
12740 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12750 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
12760 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
12770 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
12780 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12790 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20  _SCRATCH option 
127a0 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
127b0 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
127c0 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
127d0 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61  can use for scra
127e0 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54  tch memory.  ^(T
127f0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
12800 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53  rguments.** to S
12810 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12820 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72  ATCH:  A pointer
12830 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
12840 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
12850 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
12860 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  he scratch alloc
12870 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a  ations will be.*
12880 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a  * drawn, the siz
12890 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
128a0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a  h allocation (sz
128b0 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61  ),.** and the ma
128c0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
128d0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
128e0 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68  ons (N).)^.** Th
128f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
12900 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
12910 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
12920 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
12930 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
12940 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
12950 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
12960 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65  ill not use more
12970 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
12980 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
12990 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  read..** ^SQLite
129a0 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
129b0 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75  est a scratch bu
129c0 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
129d0 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
129e0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
129f0 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  age size..** ^If
12a00 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
12a10 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  eds additional.*
12a20 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
12a30 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
12a40 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
12a50 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12a60 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
12a70 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
12a80 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
12a90 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
12aa0 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a  mory needed.<p>.
12ab0 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70  ** ^When the app
12ac0 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65  lication provide
12ad0 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20  s any amount of 
12ae0 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75  scratch memory u
12af0 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43  sing.** SQLITE_C
12b00 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53  ONFIG_SCRATCH, S
12b10 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e  QLite avoids unn
12b20 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a  ecessary large.*
12b30 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
12b40 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f  c|heap allocatio
12b50 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e  ns]..** This can
12b60 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72   help [Robson pr
12b70 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f  oof|prevent memo
12b80 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
12b90 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68  ilures] due to h
12ba0 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61  eap.** fragmenta
12bb0 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f  tion in low-memo
12bc0 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  ry embedded syst
12bd0 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ems..** </dd>.**
12be0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12bf0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
12c00 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12c10 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
12c20 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
12c30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
12c40 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65  CACHE option spe
12c50 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
12c60 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a  memory buffer.**
12c70 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
12c80 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74   use for the dat
12c90 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
12ca0 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
12cb0 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  t page.** cache 
12cc0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
12cd0 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
12ce0 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
12cf0 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
12d00 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
12d10 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
12d20 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12d30 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
12d40 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
12d50 46 49 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a 20  FIG_PCACHE2].** 
12d60 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12d70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  tion..** ^There 
12d80 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
12d90 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
12da0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20  NFIG_PAGECACHE: 
12db0 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  A pointer to.** 
12dc0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a  8-byte aligned.*
12dd0 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
12de0 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
12df0 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
12e00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
12e10 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
12e20 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
12e30 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
12e40 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
12e50 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
12e60 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
12e70 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
12e80 33 32 37 36 38 29 20 70 6c 75 73 20 73 6f 6d 65  32768) plus some
12e90 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72   extra bytes for
12ea0 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
12eb0 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62  ader.  ^The numb
12ec0 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65  er of extra byte
12ed0 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20  s needed by the 
12ee0 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63  page header.** c
12ef0 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
12f00 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
12f10 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
12f20 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a  _HDRSZ] option .
12f30 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
12f40 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74  onfig()]..** ^It
12f50 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
12f60 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
12f70 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66  ted memory,.** f
12f80 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65  or the sz parame
12f90 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72  ter to be larger
12fa0 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e   than necessary.
12fb0 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
12fc0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
12fd0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
12fe0 79 74 65 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63  yte aligned bloc
12ff0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61 74  k of memory that
13000 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61 73 74 20  .** is at least 
13010 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
13020 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69 73 65 20  mory, otherwise 
13030 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
13040 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
13050 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ned..** ^SQLite 
13060 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
13070 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
13080 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
13090 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
130a0 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
130b0 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
130c0 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
130d0 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
130e0 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
130f0 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
13100 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
13110 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
13120 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
13130 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
13140 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
13150 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
13160 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
13170 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
13180 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13190 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
131a0 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
131b0 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
131c0 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
131d0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
131e0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
131f0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
13200 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74   buffer .** that
13210 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
13220 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
13230 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
13240 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a  llocation needs.
13250 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ** beyond those 
13260 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20  provided for by 
13270 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
13280 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b  CRATCH] and.** [
13290 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
132a0 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68  GECACHE]..** ^Th
132b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
132c0 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f  HEAP option is o
132d0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
132e0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
132f0 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68  led.** with eith
13300 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
13310 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53  E_MEMSYS3] or [S
13320 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
13330 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e  SYS5] and return
13340 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  s.** [SQLITE_ERR
13350 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f  OR] if invoked o
13360 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68  therwise..** ^Th
13370 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
13380 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
13390 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a  E_CONFIG_HEAP:.*
133a0 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  * An 8-byte alig
133b0 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
133c0 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
133d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
133e0 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
133f0 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
13400 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
13410 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
13420 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
13430 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
13440 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
13450 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
13460 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
13470 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
13480 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
13490 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
134a0 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
134b0 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
134c0 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
134d0 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
134e0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
134f0 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
13500 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
13510 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c  NULL then the al
13520 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
13530 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
13540 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
13550 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
13560 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
13570 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
13580 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
13590 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
135a0 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
135b0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
135c0 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
135d0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
135e0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
135f0 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
13600 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
13610 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
13620 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
13630 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
13640 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
13650 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
13660 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
13670 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
13680 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13690 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
136a0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
136b0 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
136c0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
136d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
136e0 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
136f0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13700 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20  t which is a.** 
13710 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
13720 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
13730 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13740 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
13750 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
13760 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72   specifies alter
13770 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
13780 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
13790 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e  to be used.** in
137a0 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78   place the mutex
137b0 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
137c0 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
137d0 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
137e0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
137f0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
13800 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13810 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
13820 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
13830 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
13840 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
13850 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
13860 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
13870 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
13880 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
13890 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
138a0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
138b0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
138c0 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
138d0 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
138e0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
138f0 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
13900 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
13910 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
13920 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
13930 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
13940 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
13950 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
13960 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
13970 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13980 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
13990 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
139a0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
139b0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
139c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
139d0 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  ETMUTEX option t
139e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
139f0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
13a00 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
13a10 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
13a20 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
13a30 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
13a40 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
13a50 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13a60 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
13a70 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
13a80 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
13a90 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
13aa0 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
13ab0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
13ac0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
13ad0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
13ae0 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
13af0 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
13b00 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
13b10 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
13b20 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
13b30 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
13b40 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
13b50 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
13b60 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13b70 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
13b80 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13b90 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
13ba0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
13bb0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
13bc0 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
13bd0 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
13be0 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
13bf0 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
13c00 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
13c10 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
13c20 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
13c30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13c40 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
13c50 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
13c60 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
13c70 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
13c80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13c90 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
13ca0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13cb0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
13cc0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
13cd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
13ce0 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61  KASIDE option ta
13cf0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
13d00 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
13d10 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
13d20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  size of lookasid
13d30 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68  e memory on each
13d40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13d50 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66  ction]..** The f
13d60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
13d70 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
13d80 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
13d90 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
13da0 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
13db0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
13dc0 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
13dd0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
13de0 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
13df0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13e00 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20  OKASIDE.** sets 
13e10 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  the <i>default</
13e20 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
13e30 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
13e40 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
13e50 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20  E].** option to 
13e60 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
13e70 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
13e80 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
13e90 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
13ea0 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
13eb0 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
13ec0 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
13ed0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13ee0 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
13ef0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13f00 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
13f10 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
13f20 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
13f30 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13f40 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13f50 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
13f60 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
13f70 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
13f80 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
13f90 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
13fa0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74  ifies.** the int
13fb0 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74  erface to a cust
13fc0 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
13fd0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a  plementation.)^.
13fe0 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ** ^SQLite makes
13ff0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
14000 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
14010 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
14020 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14030 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14040 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
14050 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14060 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
14070 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14080 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14090 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
140a0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
140b0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
140c0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
140d0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
140e0 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
140f0 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
14100 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20  .** the current 
14110 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
14120 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
14130 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
14140 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14150 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
14160 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14170 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
14180 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
14190 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
141a0 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
141b0 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
141c0 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
141d0 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
141e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
141f0 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
14200 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
14210 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
14220 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
14230 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
14240 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
14250 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
14260 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
14270 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
14280 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
14290 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
142a0 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
142b0 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
142c0 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
142d0 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
142e0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
142f0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
14300 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
14310 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
14320 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
14330 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
14340 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
14350 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
14360 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
14370 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14380 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
14390 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
143a0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
143b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
143c0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
143d0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
143e0 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
143f0 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
14400 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
14410 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
14420 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
14430 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
14440 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
14450 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
14460 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
14470 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
14480 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
14490 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
144a0 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
144b0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
144c0 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
144d0 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
144e0 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
144f0 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
14500 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
14510 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
14520 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
14530 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
14540 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
14550 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
14560 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
14570 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
14580 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14590 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
145a0 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
145b0 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
145c0 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
145d0 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
145e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
145f0 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
14600 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
14610 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
14620 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14630 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
14640 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
14650 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  I.** <dd>^(The S
14660 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
14670 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14680 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14690 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20  of type int..** 
146a0 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
146b0 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
146c0 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
146d0 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
146e0 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  eter is zero,.**
146f0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
14700 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ng is globally d
14710 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
14720 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
14730 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c  lobally.** enabl
14740 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
14750 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
14760 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
14770 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
14780 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
14790 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
147a0 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
147b0 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
147c0 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
147d0 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
147e0 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
147f0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
14800 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
14810 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
14820 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
14830 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
14840 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20   is opened. ^If 
14850 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
14860 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
14870 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
14880 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
14890 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
148a0 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
148b0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
148c0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
148d0 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
148e0 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55   ^(By default, U
148f0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
14900 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
14910 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
14920 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
14930 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
14940 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
14950 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
14960 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29  symbol defined.)
14970 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
14980 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
14990 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64  _INDEX_SCAN]] <d
149a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
149b0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
149c0 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  CAN.** <dd>^The 
149d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
149e0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
149f0 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  N option takes a
14a00 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a   single integer.
14a10 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ** argument whic
14a20 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
14a30 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e   as a boolean in
14a40 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
14a50 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   or disable.** t
14a60 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
14a70 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
14a80 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
14a90 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
14aa0 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  imizer..** ^The 
14ab0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
14ac0 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
14ad0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
14ae0 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
14af0 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
14b00 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
14b10 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
14b20 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
14b30 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
14b40 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
14b50 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
14b60 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
14b70 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
14b80 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
14b90 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
14ba0 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
14bb0 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
14bc0 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
14bd0 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
14be0 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
14bf0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
14c00 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
14c10 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
14c20 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
14c30 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
14c40 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
14c50 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
14c60 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
14c70 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
14c80 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
14c90 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
14ca0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14cb0 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
14cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14cd0 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
14ce0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14cf0 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
14d00 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14d10 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
14d20 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
14d30 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
14d40 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
14d50 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
14d60 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
14d70 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
14d80 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
14d90 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
14da0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14db0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
14dc0 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
14dd0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
14de0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
14df0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
14e00 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
14e10 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14e20 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
14e30 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
14e40 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
14e50 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
14e60 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
14e70 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
14e80 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
14e90 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
14ea0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
14eb0 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
14ec0 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
14ed0 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
14ee0 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
14ef0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
14f00 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
14f10 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
14f20 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
14f30 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
14f40 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
14f50 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
14f60 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
14f70 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
14f80 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
14f90 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
14fa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
14fb0 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
14fc0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14fd0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
14fe0 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
14ff0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
15000 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
15010 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
15020 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
15030 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
15040 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
15050 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
15060 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
15070 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
15080 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
15090 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
150a0 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
150b0 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
150c0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
150d0 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
150e0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
150f0 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
15100 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15110 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
15120 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
15130 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
15140 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
15150 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
15160 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
15170 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
15180 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
15190 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
151a0 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
151b0 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
151c0 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
151d0 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
151e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
151f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
15200 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
15210 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
15220 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
15230 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
15240 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
15250 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
15260 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
15270 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
15280 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
15290 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
152a0 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
152b0 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
152c0 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
152d0 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
152e0 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
152f0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
15300 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15310 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
15320 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
15330 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
15340 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
15350 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
15360 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
15370 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
15380 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
15390 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
153a0 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
153b0 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
153c0 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c  map size.** will
153d0 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75   be silently tru
153e0 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73  ncated if necess
153f0 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64  ary so that it d
15400 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74  oes not exceed t
15410 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  he.** compile-ti
15420 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20  me maximum mmap 
15430 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a  size set by the.
15440 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d  ** [SQLITE_MAX_M
15450 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c  MAP_SIZE] compil
15460 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e  e-time option.)^
15470 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61  .** ^If either a
15480 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
15490 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69  option is negati
154a0 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72  ve, then that ar
154b0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61  gument is.** cha
154c0 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70  nged to its comp
154d0 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74  ile-time default
154e0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
154f0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15500 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  APSIZE]].** <dt>
15510 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
15520 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20  N32_HEAPSIZE.** 
15530 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
15540 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
15550 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20  PSIZE option is 
15560 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
15570 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  f SQLite is.** c
15580 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64  ompiled for Wind
15590 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51  ows with the [SQ
155a0 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
155b0 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  C] pre-processor
155c0 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65   macro.** define
155d0 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  d. ^SQLITE_CONFI
155e0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
155f0 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
15600 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
15610 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
15620 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
15630 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
15640 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
15650 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dl>.**.** [[
15660 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15670 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20  ACHE_HDRSZ]].** 
15680 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15690 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a  G_PCACHE_HDRSZ.*
156a0 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
156b0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
156c0 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  HDRSZ option tak
156d0 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
156e0 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
156f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
15700 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72  n integer and wr
15710 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69  ites into that i
15720 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65  nteger the numbe
15730 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79  r of extra.** by
15740 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71  tes per page req
15750 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70  uired for each p
15760 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43  age in [SQLITE_C
15770 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
15780 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20  ..** The amount 
15790 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72  of extra space r
157a0 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e  equired can chan
157b0 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ge depending on 
157c0 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a  the compiler,.**
157d0 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d   target platform
157e0 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  , and SQLite ver
157f0 73 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  sion..** </dl>.*
15800 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15810 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
15820 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
15830 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15840 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
15850 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
15860 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15870 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
15880 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
15890 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
158a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
158b0 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
158c0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
158d0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
158e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
158f0 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
15900 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
15910 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
15920 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
15930 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
15940 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
15950 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
15960 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15970 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
15980 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
15990 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
159a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
159b0 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
159c0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
159d0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
159e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
159f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
15a00 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
15a10 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
15a20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15a30 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
15a40 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
15a50 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
15a60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15a70 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
15a80 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
15a90 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
15aa0 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
15ab0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
15ac0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
15ad0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
15ae0 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
15af0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
15b00 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
15b10 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
15b20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15b30 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
15b40 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
15b50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15b60 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
15b70 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
15b80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15b90 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
15ba0 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
15bb0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
15bc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
15bd0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
15be0 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
15bf0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15c00 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
15c10 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
15c20 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
15c30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15c40 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
15c50 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
15c60 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
15c70 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
15c80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
15c90 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
15ca0 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
15cb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15cc0 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
15cd0 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
15ce0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
15cf0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15d00 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
15d10 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
15d20 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
15d30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15d40 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15d50 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
15d60 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
15d70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15d80 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
15d90 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20  DRSZ        24  
15da0 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 0a  /* int *psz */..
15db0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
15dc0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
15dd0 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
15de0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
15df0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
15e00 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
15e10 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
15e20 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
15e30 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
15e40 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
15e50 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
15e60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
15e70 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
15e80 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
15e90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15ea0 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
15eb0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
15ec0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
15ed0 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
15ee0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15ef0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
15f00 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
15f10 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
15f20 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
15f30 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
15f40 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
15f50 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
15f60 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
15f70 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
15f80 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
15f90 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
15fa0 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
15fb0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
15fc0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
15fd0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
15fe0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
15ff0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
16000 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
16010 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
16020 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
16030 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
16040 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
16050 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
16060 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
16070 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
16080 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
16090 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
160a0 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
160b0 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
160c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
160d0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
160e0 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
160f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
16100 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
16110 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
16120 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
16130 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
16140 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
16150 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
16160 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
16170 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
16180 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
16190 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
161a0 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
161b0 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
161c0 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
161d0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
161e0 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
161f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16200 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
16210 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
16220 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
16230 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
16240 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
16250 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
16260 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
16270 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
16280 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
16290 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
162a0 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
162b0 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
162c0 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
162d0 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
162e0 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
162f0 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
16300 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
16310 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
16320 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
16330 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
16340 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
16350 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
16360 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
16370 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
16380 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
16390 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
163a0 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
163b0 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
163c0 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
163d0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
163e0 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
163f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16400 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
16410 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
16420 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
16430 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
16440 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
16450 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
16460 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
16470 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
16480 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
16490 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
164a0 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
164b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
164c0 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
164d0 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
164e0 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
164f0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
16500 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
16510 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
16520 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
16530 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
16540 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
16550 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
16560 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
16570 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
16580 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
16590 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
165a0 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
165b0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
165c0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
165d0 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
165e0 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
165f0 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
16600 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
16610 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
16620 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
16630 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
16640 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
16650 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
16660 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
16670 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
16680 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
16690 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
166a0 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
166b0 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
166c0 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
166d0 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
166e0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
166f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
16700 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
16710 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
16720 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
16730 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
16740 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
16750 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
16760 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
16770 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16780 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
16790 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
167a0 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
167b0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
167c0 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
167d0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
167e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
167f0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
16800 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
16810 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
16820 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
16830 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
16840 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
16850 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
16860 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
16870 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
16880 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
16890 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
168a0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
168b0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
168c0 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
168d0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
168e0 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
168f0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
16900 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
16910 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
16920 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16930 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
16940 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
16950 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
16960 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
16970 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
16980 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
16990 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
169a0 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
169b0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
169c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
169d0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
169e0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
169f0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
16a00 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
16a10 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
16a20 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
16a30 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
16a40 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
16a50 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
16a60 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
16a70 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
16a80 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
16a90 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
16aa0 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74      1002  /* int
16ab0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
16ac0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
16ad0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
16ae0 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e   1003  /* int in
16af0 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t* */.../*.** CA
16b00 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
16b10 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
16b20 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
16b30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
16b40 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
16b50 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
16b60 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
16b70 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
16b80 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
16b90 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
16ba0 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
16bb0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
16bc0 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
16bd0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
16be0 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
16bf0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
16c00 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
16c10 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
16c20 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
16c30 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
16c40 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
16c50 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
16c60 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
16c70 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c  most SQLite tabl
16c80 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b  es (except for [
16c90 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
16ca0 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20  ables).** has a 
16cb0 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
16cc0 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
16cd0 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
16ce0 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
16cf0 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
16d00 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
16d10 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
16d20 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
16d30 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
16d40 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
16d50 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
16d60 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
16d70 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
16d80 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
16d90 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
16da0 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
16db0 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
16dc0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
16dd0 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
16de0 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
16df0 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
16e00 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  wid..**.** ^The 
16e10 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
16e20 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74  ert_rowid(D) int
16e30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
16e40 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
16e50 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  e .** most recen
16e60 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  t successful [IN
16e70 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77  SERT] into a row
16e80 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72  id table or [vir
16e90 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f  tual table].** o
16ea0 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
16eb0 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73  ction D..** ^Ins
16ec0 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f  erts into [WITHO
16ed0 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
16ee0 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65   are not recorde
16ef0 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63  d..** ^If no suc
16f00 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
16f10 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
16f20 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  les.** have ever
16f30 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65   occurred on the
16f40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16f50 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e  tion D, .** then
16f60 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
16f70 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65  sert_rowid(D) re
16f80 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
16f90 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
16fa0 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
16fb0 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69   a trigger or wi
16fc0 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20  thin a [virtual 
16fd0 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64  table].** method
16fe0 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  , then this rout
16ff0 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ine will return 
17000 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
17010 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72  he inserted.** r
17020 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ow as long as th
17030 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
17040 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
17050 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  d is running..**
17060 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
17070 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
17080 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e   table method en
17090 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
170a0 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
170b0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
170c0 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
170d0 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
170e0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a  gger or virtual.
170f0 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  ** table method 
17100 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  began.)^.**.** ^
17110 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74  An [INSERT] that
17120 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
17130 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
17140 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
17150 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
17160 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f  ERT] and does no
17170 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
17180 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
17190 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
171a0 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52   ^Thus INSERT OR
171b0 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52   FAIL, INSERT OR
171c0 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20   IGNORE, INSERT 
171d0 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20  OR ROLLBACK,.** 
171e0 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42  and INSERT OR AB
171f0 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e  ORT make no chan
17200 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72  ges to the retur
17210 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a  n value of this.
17220 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20  ** routine when 
17230 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20  their insertion 
17240 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49  fails.  ^(When I
17250 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
17260 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
17270 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
17280 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
17290 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
172a0 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
172b0 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
172c0 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
172d0 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
172e0 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
172f0 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
17300 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
17310 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
17320 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
17330 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
17340 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  terface.)^.**.**
17350 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
17360 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
17370 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
17380 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
17390 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
173a0 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
173b0 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
173c0 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
173d0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
173e0 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53   accessible to S
173f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69  QL statements vi
17400 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69  a the.** [last_i
17410 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51  nsert_rowid() SQ
17420 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
17430 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
17440 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
17450 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
17460 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  on the same.** d
17470 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17480 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
17490 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
174a0 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75  t_rowid()].** fu
174b0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
174c0 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67  g and thus chang
174d0 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  es the last inse
174e0 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74  rt [rowid],.** t
174f0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
17500 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
17510 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
17520 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e  owid()] is.** un
17530 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
17540 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20  might not equal 
17550 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f  either the old o
17560 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73  r the new.** las
17570 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
17580 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
17590 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
175a0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
175b0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
175c0 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
175d0 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
175e0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
175f0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
17600 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
17610 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
17620 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ied, inserted or
17630 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74  .** deleted by t
17640 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
17650 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
17660 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
17670 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
17680 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
17690 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63   connection spec
176a0 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c  ified by the onl
176b0 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  y parameter..** 
176c0 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
176d0 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
176e0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
176f0 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76  not modify the v
17700 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
17710 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
17720 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63  n..**.** ^Only c
17730 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65  hanges made dire
17740 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45  ctly by the INSE
17750 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
17760 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61  LETE statement a
17770 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
17780 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61   - auxiliary cha
17790 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
177a0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
177b0 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20   triggers], .** 
177c0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
177d0 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43  ions] or [REPLAC
177e0 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
177f0 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74  solution are not
17800 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a   counted..** .**
17810 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69   Changes to a vi
17820 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
17830 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b  rcepted by .** [
17840 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
17850 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20  er | INSTEAD OF 
17860 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f  triggers] are no
17870 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20  t counted. ^The 
17880 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e  value .** return
17890 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
178a0 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74  anges() immediat
178b0 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53  ely after an INS
178c0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a  ERT, UPDATE or .
178d0 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
178e0 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65  ent run on a vie
178f0 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  w is always zero
17900 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d  . Only changes m
17910 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20  ade to real .** 
17920 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74  tables are count
17930 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73  ed..**.** Things
17940 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69   are more compli
17950 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c  cated if the sql
17960 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
17970 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78  unction is.** ex
17980 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74  ecuted while a t
17990 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69  rigger program i
179a0 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20  s running. This 
179b0 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68  may happen if th
179c0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
179d0 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  s the [changes()
179e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20   SQL function], 
179f0 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72  or if some other
17a00 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
17a10 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71  ction invokes sq
17a20 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
17a30 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74  directly. Essent
17a40 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ially:.** .** <u
17a50 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42  l>.**   <li> ^(B
17a60 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61  efore entering a
17a70 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
17a80 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
17a90 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
17aa0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
17ab0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73  () function is s
17ac0 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20  aved. After the 
17ad0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
17ae0 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66  .**        has f
17af0 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69  inished, the ori
17b00 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72  ginal value is r
17b10 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a  estored.)^.** .*
17b20 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69  *   <li> ^(Withi
17b30 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  n a trigger prog
17b40 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c  ram each INSERT,
17b50 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45   UPDATE and DELE
17b60 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74  TE .**        st
17b70 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65  atement sets the
17b80 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
17b90 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
17ba0 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
17bb0 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  upon completion 
17bc0 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f  as normal. Of co
17bd0 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65  urse, this value
17be0 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64   will not includ
17bf0 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79  e .**        any
17c00 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d   changes perform
17c10 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65  ed by sub-trigge
17c20 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74  rs, as the sqlit
17c30 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
17c40 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69          value wi
17c50 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20  ll be saved and 
17c60 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65  restored after e
17c70 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20  ach sub-trigger 
17c80 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f  has run.)^.** </
17c90 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73  ul>.** .** ^This
17ca0 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74   means that if t
17cb0 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c  he changes() SQL
17cc0 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69   function (or si
17cd0 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a  milar) is used.*
17ce0 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49  * by the first I
17cf0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
17d00 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
17d10 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
17d20 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72  er, it .** retur
17d30 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20  ns the value as 
17d40 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c  set when the cal
17d50 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62  ling statement b
17d60 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a  egan executing..
17d70 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65  ** ^If it is use
17d80 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
17d90 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75  or subsequent su
17da0 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ch statement wit
17db0 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a  hin a trigger .*
17dc0 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76  * program, the v
17dd0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65  alue returned re
17de0 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65  flects the numbe
17df0 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
17e00 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72  ed by the .** pr
17e10 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55  evious INSERT, U
17e20 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
17e30 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
17e40 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
17e50 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
17e60 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
17e70 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
17e80 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
17e90 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
17ea0 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
17eb0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
17ec0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
17ed0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
17ee0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
17ef0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
17f00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17f10 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
17f20 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
17f30 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
17f40 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
17f50 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
17f60 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
17f70 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
17f80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
17f90 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
17fa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17fb0 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
17fc0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
17fd0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
17fe0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  on returns the t
17ff0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72  otal number of r
18000 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f  ows inserted, mo
18010 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  dified or.** del
18020 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53  eted by all [INS
18030 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f  ERT], [UPDATE] o
18040 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
18050 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a  ments completed.
18060 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  ** since the dat
18070 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18080 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63   was opened, inc
18090 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65  luding those exe
180a0 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  cuted as.** part
180b0 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67   of trigger prog
180c0 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67  rams. ^Executing
180d0 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
180e0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
180f0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66  .** does not aff
18100 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  ect the value re
18110 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
18120 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
18130 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67  )..** .** ^Chang
18140 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  es made as part 
18150 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  of [foreign key 
18160 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63  actions] are inc
18170 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  luded in the.** 
18180 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65  count, but those
18190 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
181a0 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
181b0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
181c0 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e  re.** not. ^Chan
181d0 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
181e0 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
181f0 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46  ed by INSTEAD OF
18200 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72   triggers .** ar
18210 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
18220 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  * .** See also t
18230 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
18240 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
18250 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
18260 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
18270 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
18280 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
18290 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
182a0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
182b0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
182c0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
182d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
182e0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
182f0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
18300 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
18310 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
18320 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
18330 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
18340 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
18350 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
18360 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
18370 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
18380 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
18390 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
183a0 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
183b0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
183c0 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
183d0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
183e0 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
183f0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
18400 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
18410 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
18420 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
18430 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
18440 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
18450 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
18460 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
18470 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
18480 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
18490 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
184a0 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
184b0 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
184c0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
184d0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
184e0 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
184f0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
18500 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
18510 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
18520 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
18530 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
18540 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
18550 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
18560 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
18570 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
18580 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
18590 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
185a0 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
185b0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
185c0 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
185d0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
185e0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
185f0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
18600 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
18610 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
18620 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
18630 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
18640 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
18650 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
18660 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
18670 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
18680 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
18690 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
186a0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
186b0 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
186c0 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
186d0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
186e0 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
186f0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
18700 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
18710 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
18720 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
18730 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
18740 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
18750 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
18760 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
18770 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
18780 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
18790 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
187a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
187b0 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
187c0 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
187d0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
187e0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
187f0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
18800 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
18810 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
18820 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
18830 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
18840 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
18850 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
18860 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
18870 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
18880 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
18890 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
188a0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
188b0 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
188c0 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
188d0 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
188e0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
188f0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
18900 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
18910 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
18920 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
18930 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
18940 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
18950 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
18960 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
18970 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
18980 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
18990 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
189a0 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
189b0 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
189c0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
189d0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
189e0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
189f0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
18a00 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
18a10 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
18a20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
18a30 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
18a40 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
18a50 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
18a60 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
18a70 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
18a80 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
18a90 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
18aa0 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
18ab0 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
18ac0 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
18ad0 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
18ae0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18af0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
18b00 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
18b10 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
18b20 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
18b30 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
18b40 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
18b50 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
18b60 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
18b70 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
18b80 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
18b90 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
18ba0 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
18bb0 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
18bc0 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
18bd0 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
18be0 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
18bf0 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
18c00 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
18c10 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
18c20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
18c30 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
18c40 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
18c50 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
18c60 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
18c70 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
18c80 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
18c90 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
18ca0 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
18cb0 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
18cc0 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
18cd0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
18ce0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
18cf0 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
18d00 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
18d10 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
18d20 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
18d30 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
18d40 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
18d50 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
18d60 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
18d70 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
18d80 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
18d90 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
18da0 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
18db0 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
18dc0 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
18dd0 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
18de0 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
18df0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
18e00 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
18e10 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
18e20 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
18e30 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
18e40 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
18e50 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
18e60 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
18e70 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
18e80 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
18e90 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
18ea0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
18eb0 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
18ec0 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
18ed0 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
18ee0 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
18ef0 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
18f00 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
18f10 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
18f20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
18f30 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
18f40 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
18f50 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
18f60 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
18f70 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
18f80 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
18f90 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
18fa0 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
18fb0 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
18fc0 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
18fd0 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
18fe0 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
18ff0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
19000 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
19010 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
19020 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
19030 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
19040 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
19050 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
19060 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
19070 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
19080 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
19090 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
190a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
190b0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
190c0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
190d0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
190e0 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
190f0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
19100 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
19110 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
19120 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
19130 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
19140 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
19150 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
19160 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
19170 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
19180 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
19190 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
191a0 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
191b0 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
191c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
191d0 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
191e0 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
191f0 72 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r}.**.** ^The sq
19200 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
19210 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e  er(D,X,P) routin
19220 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
19230 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  k function X.** 
19240 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
19250 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
19260 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
19270 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
19280 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61  made to access a
19290 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
192a0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
192b0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
192c0 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20  nection] D when 
192d0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
192e0 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
192f0 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65   the table locke
19300 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
19310 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
19320 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
19330 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a  ed to implement.
19340 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
19350 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20  _timeout()] and 
19360 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
19370 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  eout]..**.** ^If
19380 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
19390 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
193a0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
193b0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
193c0 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
193d0 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
193e0 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
193f0 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
19400 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
19410 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
19420 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
19430 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
19440 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
19450 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
19460 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19470 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
19480 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
19490 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
194a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
194b0 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
194c0 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
194d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
194e0 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
194f0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
19500 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
19510 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
19520 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
19530 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
19540 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72  d previously for
19550 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
19560 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
19570 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
19580 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
19590 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
195a0 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
195b0 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
195c0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
195d0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
195e0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f  s returned.** to
195f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
19600 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
19610 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
19620 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
19630 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
19640 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
19650 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
19660 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
19670 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
19680 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
19690 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
196a0 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
196b0 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
196c0 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
196d0 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
196e0 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
196f0 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
19700 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
19710 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
19720 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
19730 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
19740 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
19750 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
19760 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  BUSY].** to the 
19770 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74  application inst
19780 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
19790 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e  the .** busy han
197a0 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
197b0 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
197c0 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
197d0 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
197e0 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
197f0 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
19800 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
19810 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
19820 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
19830 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
19840 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
19850 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
19860 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
19870 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
19880 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
19890 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
198a0 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
198b0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
198c0 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
198d0 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
198e0 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
198f0 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
19900 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
19910 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
19920 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
19930 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
19940 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
19950 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
19960 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
19970 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
19980 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
19990 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
199a0 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
199b0 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
199c0 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
199d0 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
199e0 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
199f0 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
19a00 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
19a10 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
19a20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
19a30 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
19a40 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
19a50 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
19a60 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
19a70 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
19a80 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
19a90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19aa0 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
19ab0 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
19ac0 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
19ad0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
19ae0 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
19af0 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
19b00 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
19b10 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76  eout()].** or ev
19b20 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41  aluating [PRAGMA
19b30 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d   busy_timeout=N]
19b40 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65   will change the
19b50 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
19b60 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20   and thus clear 
19b70 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73  any previously s
19b80 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  et busy handler.
19b90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
19ba0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
19bb0 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
19bc0 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
19bd0 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
19be0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
19bf0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
19c00 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20  sy handler.  In 
19c10 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20  other words,.** 
19c20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19c30 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
19c40 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  t.  Any such act
19c50 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
19c60 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
19c70 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
19c80 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
19c90 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
19ca0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19cb0 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
19cc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
19cd0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
19ce0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
19cf0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
19d00 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
19d10 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
19d20 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
19d30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
19d40 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
19d50 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
19d60 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
19d70 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
19d80 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
19d90 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
19da0 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
19db0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
19dc0 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
19dd0 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
19de0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
19df0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
19e00 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
19e10 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
19e20 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
19e30 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
19e40 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
19e50 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
19e60 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
19e70 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
19e80 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
19e90 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
19ea0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
19eb0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
19ec0 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  E_BUSY]..**.** ^
19ed0 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
19ee0 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
19ef0 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
19f00 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
19f10 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
19f20 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
19f30 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
19f40 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
19f50 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
19f60 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
19f70 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
19f80 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e  onnection] at an
19f90 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
19fa0 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
19fb0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
19fc0 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
19fd0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
19fe0 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
19ff0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
1a000 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
1a010 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
1a020 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
1a030 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
1a040 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  :  [PRAGMA busy_
1a050 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20  timeout].*/.int 
1a060 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1a070 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
1a080 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
1a090 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
1a0a0 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
1a0b0 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
1a0c0 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  s.**.** This is 
1a0d0 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  a legacy interfa
1a0e0 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65  ce that is prese
1a0f0 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rved for backwar
1a100 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1a110 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73  ..** Use of this
1a120 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
1a130 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  t recommended..*
1a140 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a  *.** Definition:
1a150 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62   A <b>result tab
1a160 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79  le</b> is memory
1a170 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20   data structure 
1a180 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a  created by the.*
1a190 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
1a1a0 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63  able()] interfac
1a1b0 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62  e.  A result tab
1a1c0 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a  le records the.*
1a1d0 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79  * complete query
1a1e0 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e   results from on
1a1f0 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65  e or more querie
1a200 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  s..**.** The tab
1a210 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20  le conceptually 
1a220 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  has a number of 
1a230 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73  rows and columns
1a240 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20  .  But.** these 
1a250 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20  numbers are not 
1a260 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75  part of the resu
1a270 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e  lt table itself.
1a280 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65    These.** numbe
1a290 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20  rs are obtained 
1a2a0 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74  separately.  Let
1a2b0 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   N be the number
1a2c0 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20   of rows.** and 
1a2d0 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  M be the number 
1a2e0 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a  of columns..**.*
1a2f0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1a300 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
1a310 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f  pointers to zero
1a320 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1a330 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  8 strings..** Th
1a340 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
1a350 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
1a360 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73  array.  The firs
1a370 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69  t M pointers poi
1a380 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65  nt.** to zero-te
1a390 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1a3a0 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74   that  contain t
1a3b0 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20  he names of the 
1a3c0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20  columns..** The 
1a3d0 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65  remaining entrie
1a3e0 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71  s all point to q
1a3f0 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e  uery results.  N
1a400 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c  ULL values resul
1a410 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69  t.** in NULL poi
1a420 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65  nters.  All othe
1a430 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20  r values are in 
1a440 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f  their UTF-8 zero
1a450 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1a460 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61  tring representa
1a470 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64  tion as returned
1a480 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
1a490 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
1a4a0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1a4b0 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20  e might consist 
1a4c0 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d  of one or more m
1a4d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1a4e0 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  s..** It is not 
1a4f0 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72  safe to pass a r
1a500 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65  esult table dire
1a510 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33  ctly to [sqlite3
1a520 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72  _free()]..** A r
1a530 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75  esult table shou
1a540 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ld be deallocate
1a550 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1a560 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a  _free_table()]..
1a570 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78  **.** ^(As an ex
1a580 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
1a590 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
1a5a0 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
1a5b0 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
1a5c0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1a5d0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1a5e0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
1a5f0 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
1a600 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
1a610 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a620 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
1a630 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
1a640 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
1a650 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
1a660 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
1a670 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
1a680 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1a690 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
1a6a0 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
1a6b0 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
1a6c0 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
1a6d0 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
1a6e0 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
1a6f0 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
1a700 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
1a710 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
1a720 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
1a730 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
1a740 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
1a750 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1a760 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1a770 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a780 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
1a790 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1a7a0 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
1a7b0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a7c0 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
1a7d0 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
1a7e0 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
1a7f0 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
1a800 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
1a810 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
1a820 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1a830 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
1a840 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1a850 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
1a860 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1a870 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
1a880 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1a890 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1a8a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
1a8b0 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74  et_table() funct
1a8c0 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e  ion evaluates on
1a8d0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d  e or more.** sem
1a8e0 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
1a8f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1a900 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
1a910 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
1a920 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e  string of its 2n
1a930 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
1a940 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
1a950 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
1a960 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
1a970 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
1a980 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
1a990 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1a9a0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1a9b0 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  th the result fr
1a9c0 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  om sqlite3_get_t
1a9d0 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75  able(),.** it mu
1a9e0 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75  st pass the resu
1a9f0 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72  lt table pointer
1aa00 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1aa10 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
1aa20 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20  r to.** release 
1aa30 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
1aa40 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42  was malloced.  B
1aa50 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
1aa60 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1aa70 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
1aa80 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
1aa90 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
1aaa0 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
1aab0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
1aac0 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
1aad0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
1aae0 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a  rectly.  Only.**
1aaf0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1ab00 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
1ab10 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
1ab20 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
1ab30 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
1ab40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1ab50 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61  _table() interfa
1ab60 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
1ab70 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61  d as a wrapper a
1ab80 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
1ab90 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20  3_exec()].  The 
1aba0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1abb0 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  e() routine does
1abc0 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
1abd0 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72  .** to any inter
1abe0 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75  nal data structu
1abf0 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  res of SQLite.  
1ac00 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65  It uses only the
1ac10 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72   public.** inter
1ac20 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72  face defined her
1ac30 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75  e.  As a consequ
1ac40 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61  ence, errors tha
1ac50 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a  t occur in the.*
1ac60 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20  * wrapper layer 
1ac70 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69  outside of the i
1ac80 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33  nternal [sqlite3
1ac90 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72  _exec()] call ar
1aca0 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74  e not.** reflect
1acb0 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
1acc0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1acd0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72  e3_errcode()] or
1ace0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1acf0 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  msg()]..*/.int s
1ad00 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1ad10 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1ad20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
1ad30 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
1ad40 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1ad50 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
1ad60 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
1ad70 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
1ad80 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
1ad90 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
1ada0 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
1adb0 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
1adc0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1add0 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
1ade0 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
1adf0 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
1ae00 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1ae10 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
1ae20 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
1ae30 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
1ae40 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
1ae50 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1ae60 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1ae70 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
1ae80 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
1ae90 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
1aea0 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
1aeb0 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  nting Functions.
1aec0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1aed0 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c  ines are work-al
1aee0 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
1aef0 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
1af00 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
1af10 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
1af20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  C library..**.**
1af30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70   ^The sqlite3_mp
1af40 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
1af50 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
1af60 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
1af70 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
1af80 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
1af90 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
1afa0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
1afb0 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
1afc0 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
1afd0 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
1afe0 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
1aff0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
1b000 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75  e()].  ^Both rou
1b010 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
1b020 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
1b030 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1b040 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
1b050 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
1b060 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
1b070 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
1b080 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
1b090 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e  ^(The sqlite3_sn
1b0a0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1b0b0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
1b0c0 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
1b0d0 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
1b0e0 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
1b0f0 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
1b100 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
1b110 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
1b120 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1b130 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
1b140 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
1b150 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1b160 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
1b170 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
1b180 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
1b190 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
1b1a0 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
1b1b0 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73  tf().)^  This is
1b1c0 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
1b1d0 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
1b1e0 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
1b1f0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1b200 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
1b210 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28  mpatibility.  ^(
1b220 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
1b230 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1b240 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
1b250 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
1b260 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
1b270 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
1b280 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
1b290 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
1b2a0 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20  o the buffer.)^ 
1b2b0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
1b2c0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
1b2d0 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
1b2e0 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
1b2f0 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
1b300 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
1b310 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
1b320 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
1b330 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1b340 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
1b350 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
1b360 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1b370 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73  *.** ^As long as
1b380 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
1b390 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
1b3a0 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
1b3b0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
1b3c0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
1b3d0 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
1b3e0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
1b3f0 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a  d.  ^The first.*
1b400 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
1b410 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
1b420 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
1b430 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
1b440 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
1b450 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
1b460 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
1b470 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
1b480 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
1b490 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
1b4a0 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
1b4b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b4c0 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  _vsnprintf() rou
1b4d0 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67  tine is a vararg
1b4e0 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c  s version of sql
1b4f0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e  ite3_snprintf().
1b500 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1b510 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
1b520 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
1b530 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
1b540 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
1b550 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
1b560 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
1b570 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
1b580 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
1b590 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
1b5a0 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
1b5b0 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
1b5c0 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
1b5d0 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
1b5e0 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
1b5f0 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74  .** ^(The %q opt
1b600 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1b610 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
1b620 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74  stitutes a nul-t
1b630 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1b640 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
1b650 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
1b660 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
1b670 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
1b680 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
1b690 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
1b6a0 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
1b6b0 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20   literal.)^  By 
1b6c0 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
1b6d0 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
1b6e0 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
1b6f0 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
1b700 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
1b710 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
1b720 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
1b730 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
1b740 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
1b750 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
1b760 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
1b770 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1b780 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1b790 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
1b7a0 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
1b7b0 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
1b7c0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1b7d0 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
1b7e0 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
1b7f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1b800 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1b810 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1b820 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1b830 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1b840 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1b850 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
1b860 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
1b870 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1b880 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1b890 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1b8a0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1b8b0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1b8c0 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
1b8d0 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
1b8e0 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
1b8f0 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
1b900 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
1b910 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
1b920 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
1b930 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1b940 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1b950 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1b960 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1b970 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
1b980 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
1b990 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1b9a0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
1b9b0 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
1b9c0 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
1b9d0 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
1b9e0 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
1b9f0 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
1ba00 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
1ba10 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1ba20 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1ba30 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1ba40 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1ba50 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
1ba60 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1ba70 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
1ba80 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
1ba90 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
1baa0 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
1bab0 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
1bac0 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
1bad0 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
1bae0 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
1baf0 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
1bb00 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ral..**.** ^(The
1bb10 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
1bb20 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
1bb30 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
1bb40 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
1bb50 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
1bb60 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
1bb70 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
1bb80 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
1bb90 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
1bba0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
1bbb0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
1bbc0 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
1bbd0 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
1bbe0 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
1bbf0 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53  le quotes).)^  S
1bc00 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
1bc10 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
1bc20 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1bc30 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1bc40 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1bc50 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1bc60 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1bc70 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
1bc80 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1bc90 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1bca0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1bcb0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1bcc0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1bcd0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
1bce0 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
1bcf0 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
1bd00 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1bd10 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
1bd20 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
1bd30 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
1bd40 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1bd50 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  r..**.** ^(The "
1bd60 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
1bd70 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1bd80 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
1bd90 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
1bda0 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
1bdb0 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
1bdc0 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
1bdd0 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
1bde0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1bdf0 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
1be00 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1be10 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c  .)^.*/.char *sql
1be20 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
1be30 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
1be40 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
1be50 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1be60 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
1be70 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
1be80 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1be90 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
1bea0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
1beb0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1bec0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1bed0 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a  va_list);../*.**
1bee0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1bef0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
1bf00 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65  system.**.** The
1bf10 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
1bf20 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
1bf30 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
1bf40 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
1bf50 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
1bf60 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
1bf70 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
1bf80 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
1bf90 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
1bfa0 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
1bfb0 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
1bfc0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1bfd0 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
1bfe0 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
1bff0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1c000 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
1c010 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
1c020 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
1c030 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
1c040 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1c050 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
1c060 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
1c070 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
1c080 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
1c090 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
1c0a0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
1c0b0 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
1c0c0 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
1c0d0 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
1c0e0 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
1c0f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1c100 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74   ^If the paramet
1c110 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
1c120 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
1c130 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
1c140 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
1c150 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
1c160 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1c170 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1c180 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20  te3_malloc64(N) 
1c190 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75  routine works ju
1c1a0 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74  st like.** sqlit
1c1b0 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63  e3_malloc(N) exc
1c1c0 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e  ept that N is an
1c1d0 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74   unsigned 64-bit
1c1e0 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64   integer instead
1c1f0 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20  .** of a signed 
1c200 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a  32-bit integer..
1c210 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1c220 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1c230 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1c240 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1c250 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1c260 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1c270 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1c280 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1c290 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1c2a0 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1c2b0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1c2c0 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1c2d0 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1c2e0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1c2f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1c300 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1c310 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1c320 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1c330 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1c340 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1c350 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1c360 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1c370 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1c380 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1c390 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1c3a0 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1c3b0 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1c3c0 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1c3d0 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1c3e0 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1c3f0 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1c400 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1c410 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1c420 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1c430 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1c440 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1c450 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1c460 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1c470 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1c480 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1c490 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1c4a0 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1c4b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1c4c0 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66  lloc(X,N) interf
1c4d0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
1c4e0 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
1c4f0 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
1c500 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c  ion X to be at l
1c510 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a  east N bytes..**
1c520 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d   ^If the X param
1c530 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1c540 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20  realloc(X,N).** 
1c550 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1c560 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
1c570 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
1c580 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
1c590 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1c5a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70  ..** ^If the N p
1c5b0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1c5c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1c5d0 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
1c5e0 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
1c5f0 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
1c600 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
1c610 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1c620 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20  te3_free(X)..** 
1c630 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
1c640 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20  (X,N) returns a 
1c650 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
1c660 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
1c670 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
1c680 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
1c690 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69   NULL if insuffi
1c6a0 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
1c6b0 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49  available..** ^I
1c6c0 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
1c6d0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1c6e0 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
1c6f0 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
1c700 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1c710 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
1c720 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
1c730 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
1c740 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1c750 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1c760 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  ,N) and the prio
1c770 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1c780 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
1c790 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1c7a0 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  N) returns NULL 
1c7b0 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76  and N is positiv
1c7c0 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70  e, then the.** p
1c7d0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1c7e0 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
1c7f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1c800 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20  _realloc64(X,N) 
1c810 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73  interfaces works
1c820 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20   the same as.** 
1c830 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c840 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74  X,N) except that
1c850 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75   N is a 64-bit u
1c860 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
1c870 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1c880 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
1c890 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  teger..**.** ^If
1c8a0 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61   X is a memory a
1c8b0 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f  llocation previo
1c8c0 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
1c8d0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1c8e0 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c(),.** sqlite3_
1c8f0 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69  malloc64(), sqli
1c900 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f  te3_realloc(), o
1c910 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1c920 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73  c64(), then.** s
1c930 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1c940 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
1c950 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20   of that memory 
1c960 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79  allocation in by
1c970 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  tes..** ^The val
1c980 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1c990 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1c9a0 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20  might be larger 
1c9b0 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a  than the number.
1c9c0 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75  ** of bytes requ
1c9d0 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73  ested when X was
1c9e0 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66   allocated.  ^If
1c9f0 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   X is a NULL poi
1ca00 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  nter then.** sql
1ca10 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1ca20 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20  turns zero.  If 
1ca30 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65  X points to some
1ca40 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f  thing that is no
1ca50 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69  t.** the beginni
1ca60 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  ng of memory all
1ca70 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69  ocation, or if i
1ca80 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f  t points to a fo
1ca90 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20  rmerly.** valid 
1caa0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1cab0 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62  n that has now b
1cac0 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20  een freed, then 
1cad0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
1cae0 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  of sqlite3_msize
1caf0 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  (X) is undefined
1cb00 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61   and possibly ha
1cb10 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rmful..**.** ^Th
1cb20 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
1cb30 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
1cb40 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  loc(), sqlite3_r
1cb50 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  ealloc(),.** sql
1cb60 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1cb70 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
1cb80 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61  lloc64().** is a
1cb90 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1cba0 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1cbb0 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1cbc0 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1cbd0 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1cbe0 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1cbf0 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1cc00 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1cc10 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1cc20 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1cc30 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1cc40 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1cc50 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1cc60 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1cc70 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1cc80 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1cc90 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1cca0 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1ccb0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1ccc0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1ccd0 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1cce0 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1ccf0 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1cd00 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1cd10 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1cd20 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1cd30 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
1cd40 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1cd50 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
1cd60 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1cd70 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
1cd80 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
1cd90 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1cda0 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
1cdb0 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
1cdc0 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
1cdd0 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
1cde0 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
1cdf0 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1ce00 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1ce10 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1ce20 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1ce30 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1ce40 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1ce50 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
1ce60 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
1ce70 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
1ce80 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
1ce90 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
1cea0 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
1ceb0 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
1cec0 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
1ced0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
1cee0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
1cef0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1cf00 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1cf10 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
1cf20 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
1cf30 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
1cf40 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
1cf50 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
1cf60 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1cf70 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
1cf80 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1cf90 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
1cfa0 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
1cfb0 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
1cfc0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
1cfd0 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
1cfe0 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
1cff0 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
1d000 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
1d010 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
1d020 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1d030 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
1d040 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d050 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
1d060 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1d070 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
1d080 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f  alloc64(sqlite3_
1d090 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73  uint64);.void *s
1d0a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
1d0b0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
1d0c0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1d0d0 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74  c64(void*, sqlit
1d0e0 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64  e3_uint64);.void
1d0f0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
1d100 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69  id*);.sqlite3_ui
1d110 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69  nt64 sqlite3_msi
1d120 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ze(void*);../*.*
1d130 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1d140 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
1d150 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
1d160 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
1d170 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
1d180 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
1d190 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
1d1a0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
1d1b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
1d1c0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
1d1d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1d1e0 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
1d1f0 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
1d200 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
1d210 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
1d220 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
1d230 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1d240 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
1d250 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1d260 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
1d270 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
1d280 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
1d290 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
1d2a0 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
1d2b0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1d2c0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1d2d0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1d2e0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1d2f0 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
1d300 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1d310 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
1d320 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
1d330 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
1d340 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
1d350 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1d360 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1d370 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1d380 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1d390 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
1d3a0 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
1d3b0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
1d3c0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
1d3d0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1d3e0 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
1d3f0 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
1d400 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
1d410 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
1d420 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
1d430 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
1d440 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
1d450 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
1d460 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
1d470 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
1d480 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
1d490 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
1d4a0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1d4b0 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
1d4c0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1d4d0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1d4e0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1d4f0 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
1d500 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1d510 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1d520 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1d530 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
1d540 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1d550 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
1d560 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
1d570 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1d580 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
1d590 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1d5a0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1d5b0 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
1d5c0 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
1d5d0 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
1d5e0 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
1d5f0 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
1d600 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
1d610 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
1d620 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
1d630 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
1d640 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
1d650 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
1d660 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
1d670 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
1d680 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
1d690 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
1d6a0 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
1d6b0 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
1d6c0 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
1d6d0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
1d6e0 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
1d6f0 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
1d700 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
1d710 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
1d720 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1d730 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
1d740 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
1d750 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
1d760 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
1d770 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
1d780 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
1d790 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
1d7a0 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
1d7b0 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20  ffer P..** ^The 
1d7c0 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  P parameter can 
1d7d0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
1d7e0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69  r..**.** ^If thi
1d7f0 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f  s routine has no
1d800 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c  t been previousl
1d810 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74  y called or if t
1d820 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63  he previous.** c
1d830 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74  all had N less t
1d840 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c  han one or a NUL
1d850 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c  L pointer for P,
1d860 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69   then the PRNG i
1d870 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e  s.** seeded usin
1d880 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
1d890 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78  ained from the x
1d8a0 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
1d8b0 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61  d of.** the defa
1d8c0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1d8d0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66  ] object..** ^If
1d8e0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
1d8f0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1d900 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31  ne had an N of 1
1d910 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a   or more and a.*
1d920 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65  * non-NULL P the
1d930 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  n the pseudo-ran
1d940 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
1d950 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
1d960 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
1d970 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
1d980 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
1d990 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
1d9a0 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  od..*/.void sqli
1d9b0 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
1d9c0 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
1d9d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d9e0 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
1d9f0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
1da00 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  backs.**.** ^Thi
1da10 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
1da20 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ers an authorize
1da30 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
1da40 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1da50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1da60 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
1da70 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
1da80 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
1da90 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1daa0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
1dab0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1dac0 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
1dad0 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1dae0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1daf0 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
1db00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1db10 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1db20 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
1db30 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
1db40 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
1db50 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
1db60 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
1db70 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
1db80 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
1db90 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
1dba0 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
1dbb0 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
1dbc0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1dbd0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
1dbe0 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
1dbf0 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
1dc00 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
1dc10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1dc20 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
1dc30 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
1dc40 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
1dc50 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
1dc60 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
1dc70 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
1dc80 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
1dc90 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1dca0 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
1dcb0 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
1dcc0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1dcd0 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
1dce0 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
1dcf0 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
1dd00 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
1dd10 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
1dd20 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1dd30 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
1dd40 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
1dd50 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
1dd60 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
1dd70 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1dd80 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
1dd90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1dda0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
1ddb0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
1ddc0 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
1ddd0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
1dde0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
1ddf0 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
1de00 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1de10 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1de20 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
1de30 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
1de40 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
1de50 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
1de60 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1de70 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
1de80 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
1de90 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
1dea0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
1deb0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
1dec0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1ded0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
1dee0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
1def0 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
1df00 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
1df10 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
1df20 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1df30 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1df40 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
1df50 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
1df60 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
1df70 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
1df80 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
1df90 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
1dfa0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1dfb0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1dfc0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1dfd0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
1dfe0 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
1dff0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1e000 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
1e010 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1e020 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
1e030 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
1e040 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
1e050 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
1e060 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
1e070 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1e080 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
1e090 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
1e0a0 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
1e0b0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1e0c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
1e0d0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1e0e0 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
1e0f0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1e100 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1e110 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1e120 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
1e130 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
1e140 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
1e150 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
1e160 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
1e170 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
1e180 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
1e190 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
1e1a0 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
1e1b0 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
1e1c0 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
1e1d0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1e1e0 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
1e1f0 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
1e200 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
1e210 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
1e220 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
1e230 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
1e240 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1e250 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
1e260 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
1e270 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1e280 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
1e290 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
1e2a0 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
1e2b0 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
1e2c0 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
1e2d0 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
1e2e0 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
1e2f0 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
1e300 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
1e310 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
1e320 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
1e330 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1e340 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
1e350 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
1e360 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
1e370 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
1e380 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
1e390 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
1e3a0 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
1e3b0 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
1e3c0 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
1e3d0 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
1e3e0 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
1e3f0 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
1e400 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
1e410 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
1e420 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
1e430 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
1e440 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
1e450 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
1e460 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
1e470 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
1e480 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
1e490 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
1e4a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1e4b0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
1e4c0 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
1e4d0 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
1e4e0 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
1e4f0 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
1e500 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
1e510 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
1e520 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
1e530 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
1e540 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
1e550 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1e560 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
1e570 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
1e580 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
1e590 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
1e5a0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1e5b0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
1e5c0 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
1e5d0 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
1e5e0 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
1e5f0 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
1e600 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
1e610 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
1e620 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
1e630 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
1e640 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
1e650 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
1e660 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1e670 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
1e680 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
1e690 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
1e6a0 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
1e6b0 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
1e6c0 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
1e6d0 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
1e6e0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
1e6f0 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
1e700 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
1e710 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
1e720 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
1e730 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
1e740 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
1e750 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
1e760 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
1e770 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
1e780 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
1e790 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
1e7a0 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
1e7b0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
1e7c0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
1e7d0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1e7e0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1e7f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1e800 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
1e810 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e820 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
1e830 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e840 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1e850 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1e860 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1e870 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1e880 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1e890 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1e8a0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1e8b0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
1e8c0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1e8d0 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
1e8e0 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
1e8f0 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
1e900 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
1e910 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
1e920 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
1e930 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
1e940 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
1e950 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
1e960 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
1e970 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
1e980 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
1e990 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e9a0 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
1e9b0 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
1e9c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1e9d0 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
1e9e0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1e9f0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1ea00 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
1ea10 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1ea20 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1ea30 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
1ea40 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
1ea50 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
1ea60 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
1ea70 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
1ea80 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
1ea90 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
1eaa0 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
1eab0 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
1eac0 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
1ead0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
1eae0 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
1eaf0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1eb00 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
1eb10 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
1eb20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1eb30 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
1eb40 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
1eb50 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
1eb60 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1eb70 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1eb80 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
1eb90 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
1eba0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1ebb0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1ebc0 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
1ebd0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1ebe0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1ebf0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ec00 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
1ec10 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
1ec20 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
1ec30 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
1ec40 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
1ec50 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
1ec60 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
1ec70 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
1ec80 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
1ec90 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
1eca0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1ecb0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1ecc0 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
1ecd0 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
1ece0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1ecf0 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
1ed00 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
1ed10 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
1ed20 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73   a [conflict res
1ed30 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a  olution mode].**
1ed40 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74   returned from t
1ed50 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
1ed60 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
1ed70 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
1ed80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
1ed90 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
1eda0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1edb0 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
1edc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1edd0 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
1ede0 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
1edf0 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
1ee00 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
1ee10 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1ee20 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1ee30 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
1ee40 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1ee50 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1ee60 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
1ee70 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
1ee80 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
1ee90 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
1eea0 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
1eeb0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1eec0 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
1eed0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1eee0 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
1eef0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1ef00 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
1ef10 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
1ef20 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
1ef30 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
1ef40 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
1ef50 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
1ef60 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1ef70 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
1ef80 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
1ef90 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
1efa0 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
1efb0 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
1efc0 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
1efd0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
1efe0 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
1eff0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
1f000 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
1f010 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
1f020 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
1f030 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
1f040 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
1f050 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
1f060 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
1f070 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1f080 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
1f090 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1f0a0 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1f0b0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1f0c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
1f0d0 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
1f0e0 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
1f0f0 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
1f100 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
1f110 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1f120 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1f130 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
1f140 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
1f150 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
1f160 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
1f170 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
1f180 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1f190 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
1f1a0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
1f1b0 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
1f1c0 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
1f1d0 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
1f1e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f1f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f200 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
1f210 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
1f220 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
1f230 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
1f240 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
1f250 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1f260 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1f270 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f280 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
1f290 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
1f2a0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f2b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f2c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f2d0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1f2e0 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
1f2f0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1f300 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1f310 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f320 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1f330 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
1f340 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f350 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f360 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f370 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1f380 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
1f390 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1f3a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f3b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f3c0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
1f3d0 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
1f3e0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1f3f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f400 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f410 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
1f420 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
1f430 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1f440 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f450 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f460 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
1f470 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
1f480 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1f490 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f4a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f4b0 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
1f4c0 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
1f4d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1f4e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f4f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f500 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
1f510 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
1f520 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1f530 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1f540 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f550 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
1f560 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
1f570 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f580 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f590 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f5a0 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
1f5b0 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
1f5c0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1f5d0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1f5e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f5f0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1f600 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
1f610 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f620 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f630 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f640 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
1f650 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
1f660 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1f670 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f680 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1f690 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
1f6a0 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
1f6b0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f6c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f6d0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
1f6e0 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
1f6f0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1f700 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1f710 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f720 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
1f730 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
1f740 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1f750 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f760 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f770 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
1f780 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
1f790 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f7a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f7b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f7c0 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
1f7d0 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
1f7e0 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
1f7f0 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
1f800 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
1f810 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
1f820 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
1f830 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f840 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
1f850 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f860 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
1f870 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
1f880 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f890 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f8a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f8b0 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
1f8c0 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
1f8d0 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
1f8e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f8f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f900 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
1f910 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
1f920 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
1f930 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
1f940 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f950 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
1f960 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
1f970 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
1f980 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f990 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f9a0 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
1f9b0 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
1f9c0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
1f9d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f9e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1f9f0 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
1fa00 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
1fa10 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
1fa20 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1fa30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1fa40 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
1fa50 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
1fa60 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1fa70 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1fa80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
1fa90 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
1faa0 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
1fab0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1fac0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1fad0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1fae0 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
1faf0 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
1fb00 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1fb10 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1fb20 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1fb30 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
1fb40 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
1fb50 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1fb60 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1fb70 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
1fb80 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
1fb90 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1fba0 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
1fbb0 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
1fbc0 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
1fbd0 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
1fbe0 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1fbf0 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
1fc00 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
1fc10 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
1fc20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
1fc30 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
1fc40 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  sed */.#define S
1fc50 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20  QLITE_RECURSIVE 
1fc60 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20             33   
1fc70 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1fc80 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1fc90 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     */../*.** CAP
1fca0 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
1fcb0 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
1fcc0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1fcd0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
1fce0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
1fcf0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
1fd00 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
1fd10 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
1fd20 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
1fd30 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
1fd40 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1fd50 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1fd60 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1fd70 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
1fd80 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
1fd90 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
1fda0 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
1fdb0 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
1fdc0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
1fdd0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
1fde0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1fdf0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1fe00 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
1fe10 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
1fe20 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
1fe30 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
1fe40 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
1fe50 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
1fe60 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
1fe70 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
1fe80 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
1fe90 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
1fea0 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
1feb0 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
1fec0 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
1fed0 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
1fee0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
1fef0 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
1ff00 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
1ff10 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
1ff20 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
1ff30 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
1ff40 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1ff50 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
1ff60 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
1ff70 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
1ff80 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
1ff90 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
1ffa0 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
1ffb0 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
1ffc0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1ffd0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1ffe0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
1fff0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
20000 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
20010 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
20020 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
20030 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
20040 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
20050 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
20060 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
20070 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
20080 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
20090 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
200a0 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
200b0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
200c0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
200d0 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
200e0 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
200f0 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
20100 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
20110 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
20120 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
20130 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
20140 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
20150 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
20160 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
20170 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
20180 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
20190 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
201a0 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
201b0 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
201c0 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
201d0 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
201e0 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
201f0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
20200 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
20210 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
20220 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
20230 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
20240 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
20250 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
20260 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
20270 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
20280 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
20290 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
202a0 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
202b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
202c0 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
202d0 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
202e0 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
202f0 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
20300 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
20310 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20320 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
20330 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
20340 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
20350 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
20360 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
20370 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
20380 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
20390 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
203a0 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
203b0 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
203c0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
203d0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
203e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
203f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
20400 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
20410 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20420 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
20430 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
20440 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
20450 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
20460 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
20470 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
20480 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
20490 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
204a0 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
204b0 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
204c0 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
204d0 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
204e0 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
204f0 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65   the approximate
20500 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
20510 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
20520 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
20530 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
20540 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
20550 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
20560 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
20570 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20  ck X.  ^If N is 
20580 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68  less than one th
20590 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a  en the progress.
205a0 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69  ** handler is di
205b0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  sabled..**.** ^O
205c0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
205d0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
205e0 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
205f0 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
20600 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
20610 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
20620 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
20630 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
20640 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
20650 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
20660 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
20670 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
20680 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
20690 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
206a0 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
206b0 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
206c0 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
206d0 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
206e0 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
206f0 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
20700 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
20710 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
20720 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
20730 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
20740 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
20750 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
20760 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
20770 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
20780 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
20790 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
207a0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
207b0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
207c0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
207d0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
207e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
207f0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
20800 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
20810 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
20820 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20830 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
20840 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
20850 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
20860 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20870 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
20880 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
20890 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
208a0 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  ph..**.*/.void s
208b0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
208c0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
208d0 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
208e0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
208f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
20900 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
20910 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
20920 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
20930 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
20940 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
20950 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
20960 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
20970 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
20980 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
20990 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
209a0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
209b0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
209c0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
209d0 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
209e0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
209f0 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
20a00 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
20a10 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
20a20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20a30 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
20a40 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
20a50 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
20a60 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
20a70 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
20a80 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
20a90 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
20aa0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
20ab0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
20ac0 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
20ad0 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
20ae0 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
20af0 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
20b00 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
20b10 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
20b20 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
20b30 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
20b40 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
20b50 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
20b60 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
20b70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
20b80 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
20b90 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
20ba0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
20bb0 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
20bc0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
20bd0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
20be0 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
20bf0 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
20c00 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
20c10 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
20c20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
20c30 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
20c40 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
20c50 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
20c60 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
20c70 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
20c80 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
20c90 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  ng will be UTF-8
20ca0 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63   for databases c
20cb0 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
20cc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
20cd0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
20ce0 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75  2().  ^The defau
20cf0 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
20d00 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65  databases.** cre
20d10 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74  ated using sqlit
20d20 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c  e3_open16() will
20d30 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68   be UTF-16 in th
20d40 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
20d50 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  der..**.** Wheth
20d60 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
20d70 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
20d80 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
20d90 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
20da0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
20db0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20dc0 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
20dd0 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
20de0 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
20df0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
20e00 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
20e10 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
20e20 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
20e30 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
20e40 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
20e50 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
20e60 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
20e70 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
20e80 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
20e90 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
20ea0 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
20eb0 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
20ec0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20ed0 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
20ee0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
20ef0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20f00 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
20f10 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
20f20 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
20f30 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
20f40 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
20f50 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
20f60 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
20f70 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
20f80 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
20f90 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
20fa0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
20fb0 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
20fc0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
20fd0 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
20fe0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
20ff0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
21000 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
21010 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
21020 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
21030 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
21040 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
21050 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
21060 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
21070 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
21080 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
21090 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
210a0 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
210b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
210c0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
210d0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
210e0 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
210f0 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
21100 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
21110 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
21120 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
21130 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
21140 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
21150 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
21160 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
21170 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
21180 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
21190 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
211a0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
211b0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
211c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
211d0 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
211e0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
211f0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
21200 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
21210 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
21220 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
21230 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
21240 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
21250 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
21260 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
21270 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21280 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
21290 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
212a0 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
212b0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
212c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
212d0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
212e0 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
212f0 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
21300 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
21310 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
21320 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
21330 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
21340 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
21350 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
21360 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
21370 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
21380 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
21390 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
213a0 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
213b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
213c0 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
213d0 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
213e0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
213f0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
21400 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
21410 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
21420 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
21430 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
21440 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
21450 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
21460 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
21470 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
21480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21490 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
214a0 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
214b0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
214c0 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
214d0 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
214e0 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
214f0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
21500 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
21510 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
21520 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
21530 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
21540 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21550 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
21560 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
21570 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
21580 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
21590 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
215a0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
215b0 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
215c0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
215d0 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
215e0 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
215f0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
21600 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
21610 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
21620 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
21630 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
21640 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
21650 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
21660 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
21670 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
21680 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
21690 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
216a0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
216b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
216c0 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
216d0 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
216e0 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
216f0 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
21700 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
21710 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
21720 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
21730 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
21740 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
21750 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
21760 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
21770 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
21780 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
21790 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
217a0 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
217b0 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
217c0 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
217d0 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
217e0 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
217f0 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
21800 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
21810 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
21820 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
21830 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
21840 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
21850 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
21860 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
21870 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
21880 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
21890 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
218a0 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
218b0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
218c0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
218d0 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
218e0 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
218f0 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
21900 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
21910 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
21920 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
21930 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
21940 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
21950 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
21960 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
21970 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
21980 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
21990 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
219a0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
219b0 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
219c0 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
219d0 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
219e0 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
219f0 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
21a00 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
21a10 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
21a20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21a30 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
21a40 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
21a50 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
21a60 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
21a70 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
21a80 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
21a90 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
21aa0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
21ab0 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
21ac0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
21ad0 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
21ae0 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
21af0 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
21b00 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
21b10 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
21b20 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
21b30 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
21b40 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
21b50 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74  ] flag is.** set
21b60 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61   in the fourth a
21b70 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
21b80 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72  e3_open_v2(), or
21b90 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65   if it has.** be
21ba0 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61  en enabled globa
21bb0 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53  lly using the [S
21bc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
21bd0 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68  ] option with th
21be0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
21bf0 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f  nfig()] method o
21c00 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  r by the [SQLITE
21c10 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c  _USE_URI] compil
21c20 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
21c30 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76  * As of SQLite v
21c40 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52  ersion 3.7.7, UR
21c50 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  I filename inter
21c60 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72  pretation is tur
21c70 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65  ned off.** by de
21c80 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72  fault, but futur
21c90 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
21ca0 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c  Lite might enabl
21cb0 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a  e URI filename.*
21cc0 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  * interpretation
21cd0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65   by default.  Se
21ce0 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  e "[URI filename
21cf0 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  s]" for addition
21d00 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
21d10 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c  n..**.** URI fil
21d20 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65  enames are parse
21d30 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52  d according to R
21d40 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65  FC 3986. ^If the
21d50 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e   URI contains an
21d60 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74  .** authority, t
21d70 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65  hen it must be e
21d80 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73  ither an empty s
21d90 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72  tring or the str
21da0 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f  ing .** "localho
21db0 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74  st". ^If the aut
21dc0 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e  hority is not an
21dd0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
21de0 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e   "localhost", an
21df0 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65   .** error is re
21e00 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61  turned to the ca
21e10 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d  ller. ^The fragm
21e20 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ent component of
21e30 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70   a URI, if .** p
21e40 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72  resent, is ignor
21e50 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
21e60 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20  e uses the path 
21e70 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65  component of the
21e80 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65   URI as the name
21e90 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c   of the disk fil
21ea0 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61  e.** which conta
21eb0 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ins the database
21ec0 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62  . ^If the path b
21ed0 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27  egins with a '/'
21ee0 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20   character, .** 
21ef0 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72  then it is inter
21f00 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73  preted as an abs
21f10 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20  olute path. ^If 
21f20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f  the path does no
21f30 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68  t begin .** with
21f40 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20   a '/' (meaning 
21f50 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
21f60 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d  ty section is om
21f70 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55  itted from the U
21f80 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  RI).** then the 
21f90 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65  path is interpre
21fa0 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76  ted as a relativ
21fb0 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e  e path. .** ^(On
21fc0 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
21fd0 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
21fe0 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
21ff0 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
22000 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
22010 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a  e.g. "C:").)^.**
22020 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71  .** [[core URI q
22030 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d  uery parameters]
22040 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63  ].** The query c
22050 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
22060 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61  I may contain pa
22070 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72  rameters that ar
22080 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a  e interpreted.**
22090 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74   either by SQLit
220a0 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20  e itself, or by 
220b0 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20  a [VFS | custom 
220c0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
220d0 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61  on]..** SQLite a
220e0 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20  nd its built-in 
220f0 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65  [VFSes] interpre
22100 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  t the.** followi
22110 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ng query paramet
22120 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ers:.**.** <ul>.
22130 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73  **   <li> <b>vfs
22140 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22  </b>: ^The "vfs"
22150 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
22160 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66  e used to specif
22170 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a  y the name of.**
22180 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63       a VFS objec
22190 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20  t that provides 
221a0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
221b0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
221c0 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20  hat should.**   
221d0 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63    be used to acc
221e0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
221f0 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e   file on disk. ^
22200 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  If this option i
22210 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20  s set to.**     
22220 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
22230 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
22240 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20  object is used. 
22250 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
22260 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46  nknown.**     VF
22270 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e  S is an error. ^
22280 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
22290 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
222a0 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20   the vfs option 
222b0 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e  is.**     presen
222c0 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20  t, then the VFS 
222d0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
222e0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72   option takes pr
222f0 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a  ecedence over.**
22300 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70       the value p
22310 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
22320 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
22330 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22340 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
22350 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28   <b>mode</b>: ^(
22360 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  The mode paramet
22370 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
22380 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72   either "ro", "r
22390 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22  w",.**     "rwc"
223a0 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41  , or "memory". A
223b0 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74  ttempting to set
223c0 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72   it to any other
223d0 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20   value is.**    
223e0 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a   an error)^. .**
223f0 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73       ^If "ro" is
22400 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
22410 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
22420 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
22430 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63  -only .**     ac
22440 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66  cess, just as if
22450 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
22460 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67  N_READONLY] flag
22470 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e   had been set in
22480 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69   the .**     thi
22490 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
224a0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
224b0 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f  . ^If the mode o
224c0 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20  ption is set to 
224d0 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68  .**     "rw", th
224e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
224f0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
22500 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f  ad-write (but no
22510 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20  t create) .**   
22520 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20    access, as if 
22530 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
22540 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53  WRITE (but not S
22550 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
22560 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62  E) had .**     b
22570 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20  een set. ^Value 
22580 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c  "rwc" is equival
22590 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62  ent to setting b
225a0 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49  oth .**     SQLI
225b0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
225c0 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45  E and SQLITE_OPE
225d0 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74  N_CREATE.  ^If t
225e0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
225f0 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20  s.**     set to 
22600 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20  "memory" then a 
22610 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20  pure [in-memory 
22620 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e  database] that n
22630 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20  ever reads.**   
22640 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d    or writes from
22650 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e   disk is used. ^
22660 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
22670 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
22680 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65  e for.**     the
22690 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
226a0 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73  that is less res
226b0 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68  trictive than th
226c0 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  at specified by.
226d0 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73  **     the flags
226e0 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74   passed in the t
226f0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
22700 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
22710 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
22720 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20  > <b>cache</b>: 
22730 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d  ^The cache param
22740 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
22750 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65  to either "share
22760 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72  d" or.**     "pr
22770 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67  ivate". ^Setting
22780 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20   it to "shared" 
22790 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
227a0 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20   setting the.** 
227b0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
227c0 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20  SHAREDCACHE bit 
227d0 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  in the flags arg
227e0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a  ument passed to.
227f0 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f  **     sqlite3_o
22800 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69  pen_v2(). ^Setti
22810 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72  ng the cache par
22820 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61  ameter to "priva
22830 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65  te" is .**     e
22840 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
22850 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  ting the SQLITE_
22860 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
22870 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49  E bit..**     ^I
22880 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
22890 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
228a0 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61  the "cache" para
228b0 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74  meter is present
228c0 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49   in.**     a URI
228d0 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76   filename, its v
228e0 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61  alue overrides a
228f0 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75  ny behavior requ
22900 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67  ested by setting
22910 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
22920 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
22930 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   or SQLITE_OPEN_
22940 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67  SHAREDCACHE flag
22950 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
22960 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20  >psow</b>: ^The 
22970 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69  psow parameter i
22980 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72  ndicates whether
22990 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20   or not the.**  
229a0 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76     [powersafe ov
229b0 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74  erwrite] propert
229c0 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e  y does or does n
229d0 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a  ot apply to the.
229e0 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d  **     storage m
229f0 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68  edia on which th
22a00 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
22a10 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20  resides..**.**  
22a20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f  <li> <b>nolock</
22a30 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20  b>: ^The nolock 
22a40 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
22a50 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72  oolean query par
22a60 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68  ameter.**     wh
22a70 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62  ich if set disab
22a80 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67  les file locking
22a90 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75   in rollback jou
22aa0 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69  rnal modes.  Thi
22ab0 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66  s.**     is usef
22ac0 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67  ul for accessing
22ad0 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61   a database on a
22ae0 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74   filesystem that
22af0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20   does not.**    
22b00 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67   support locking
22b10 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74  .  Caution:  Dat
22b20 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
22b30 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
22b40 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d   two.**     or m
22b50 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72  ore processes wr
22b60 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20  ite to the same 
22b70 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79  database and any
22b80 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a   one of those.**
22b90 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75       processes u
22ba0 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a  ses nolock=1..**
22bb0 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d  .**  <li> <b>imm
22bc0 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65  utable</b>: ^The
22bd0 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d   immutable param
22be0 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
22bf0 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70  n query.**     p
22c00 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e  arameter that in
22c10 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65  dicates that the
22c20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
22c30 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20  s stored on.**  
22c40 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64     read-only med
22c50 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74  ia.  ^When immut
22c60 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c  able is set, SQL
22c70 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
22c80 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61   the.**     data
22c90 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74  base file cannot
22ca0 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65   be changed, eve
22cb0 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77  n by a process w
22cc0 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20  ith higher.**   
22cd0 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64    privilege, and
22ce0 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   so the database
22cf0 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d   is opened read-
22d00 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63  only and all loc
22d10 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20  king.**     and 
22d20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e  change detection
22d30 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43   is disabled.  C
22d40 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20  aution: Setting 
22d50 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a  the immutable.**
22d60 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e       property on
22d70 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
22d80 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61   that does in fa
22d90 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65  ct change can re
22da0 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69  sult.**     in i
22db0 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72  ncorrect query r
22dc0 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53  esults and/or [S
22dd0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65  QLITE_CORRUPT] e
22de0 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65  rrors..**     Se
22df0 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f  e also: [SQLITE_
22e00 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d  IOCAP_IMMUTABLE]
22e10 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c  ..**       .** <
22e20 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63  /ul>.**.** ^Spec
22e30 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
22e40 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  n parameter in t
22e50 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
22e60 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e  nt of a URI is n
22e70 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  ot an.** error. 
22e80 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
22e90 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
22ea0 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69   understand addi
22eb0 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20  tional query.** 
22ec0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65  parameters.  See
22ed0 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74   "[query paramet
22ee0 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c  ers with special
22ef0 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69   meaning to SQLi
22f00 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69  te]" for.** addi
22f10 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
22f20 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  on..**.** [[URI 
22f30 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
22f40 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65  s]] <h3>URI file
22f50 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68  name examples</h
22f60 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  3>.**.** <table 
22f70 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
22f80 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
22f90 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
22fa0 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
22fb0 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
22fc0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
22fd0 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
22fe0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
22ff0 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
23000 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
23010 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
23020 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
23030 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
23040 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
23050 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
23060 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
23070 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
23080 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
23090 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
230a0 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
230b0 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
230c0 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
230d0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
230e0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
230f0 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
23100 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
23110 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
23120 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
23130 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
23140 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
23150 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
23160 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
23170 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
23180 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
23190 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
231a0 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
231b0 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
231c0 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
231d0 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
231e0 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
231f0 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
23200 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
23210 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
23220 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
23230 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
23240 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
23250 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
23260 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
23270 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
23280 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
23290 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
232a0 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
232b0 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
232c0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
232d0 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
232e0 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
232f0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
23300 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
23310 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
23320 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
23330 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
23340 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
23350 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
23360 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
23370 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
23380 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
23390 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
233a0 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
233b0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
233c0 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
233d0 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64  ta.db?vfs=unix-d
233e0 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20  otfile <td>.**  
233f0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
23400 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
23410 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20  ta.db". Use the 
23420 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69  special VFS "uni
23430 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20  x-dotfile".**   
23440 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73         that uses
23450 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c   dot-files in pl
23460 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76  ace of posix adv
23470 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a  isory locking..*
23480 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
23490 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61  data.db?mode=rea
234a0 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20  donly <td> .**  
234b0 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
234c0 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20  . "readonly" is 
234d0 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69  not a valid opti
234e0 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65  on for the "mode
234f0 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  " parameter..** 
23500 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e  </table>.**.** ^
23510 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20  URI hexadecimal 
23520 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
23530 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f   (%HH) are suppo
23540 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20  rted within the 
23550 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72  path and.** quer
23560 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
23570 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63  a URI. A hexadec
23580 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
23590 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66  ence consists of
235a0 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69   a.** percent si
235b0 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f  gn - "%" - follo
235c0 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74  wed by exactly t
235d0 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  wo hexadecimal d
235e0 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66  igits .** specif
235f0 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61  ying an octet va
23600 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65  lue. ^Before the
23610 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63   path or query c
23620 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a  omponents of a.*
23630 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61  * URI filename a
23640 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20  re interpreted, 
23650 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64  they are encoded
23660 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64   using UTF-8 and
23670 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63   all .** hexadec
23680 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
23690 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62  ences replaced b
236a0 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20  y a single byte 
236b0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a  containing the.*
236c0 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  * corresponding 
236d0 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70  octet. If this p
236e0 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73  rocess generates
236f0 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d   an invalid UTF-
23700 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74  8 encoding,.** t
23710 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
23720 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
23730 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
23740 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
23750 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
23760 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
23770 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
23780 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
23790 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
237a0 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
237b0 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
237c0 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
237d0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
237e0 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
237f0 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
23800 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
23810 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
23820 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
23830 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
23840 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
23850 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
23860 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23870 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ()..**.** <b>Not
23880 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e  e to Windows Run
23890 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20  time users:</b> 
238a0 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64   The temporary d
238b0 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65  irectory must be
238c0 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f   set.** prior to
238d0 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
238e0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
238f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f  e3_open_v2().  O
23900 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75  therwise, variou
23910 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68  s.** features th
23920 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75  at require the u
23930 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20  se of temporary 
23940 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a  files may fail..
23950 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
23960 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  [sqlite3_temp_di
23970 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20  rectory].*/.int 
23980 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
23990 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
239a0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
239b0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
239c0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
239d0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
239e0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
239f0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
23a00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
23a10 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
23a20 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
23a30 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
23a40 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
23a50 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
23a60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
23a70 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
23a80 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
23a90 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
23aa0 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
23ab0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
23ac0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
23ad0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
23ae0 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
23af0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
23b00 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
23b10 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
23b20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
23b30 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
23b40 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
23b50 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
23b60 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
23b70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23b80 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20  : Obtain Values 
23b90 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65  For URI Paramete
23ba0 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  rs.**.** These a
23bb0 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69  re utility routi
23bc0 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56  nes, useful to V
23bd0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
23be0 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a  ns, that check.*
23bf0 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61  * to see if a da
23c00 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20  tabase file was 
23c10 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61  a URI that conta
23c20 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20  ined a specific 
23c30 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65  query .** parame
23c40 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f  ter, and if so o
23c50 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65  btains the value
23c60 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70   of that query p
23c70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
23c80 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61  If F is the data
23c90 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f  base filename po
23ca0 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74  inter passed int
23cb0 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65  o the xOpen() me
23cc0 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46  thod of .** a VF
23cd0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
23ce0 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20   when the flags 
23cf0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
23d00 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20  en() has one or 
23d10 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20  .** more of the 
23d20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
23d30 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
23d40 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20  N_MAIN_DB] bits 
23d50 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20  set and.** P is 
23d60 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
23d70 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c  query parameter,
23d80 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
23d90 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
23da0 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  ,P) returns the 
23db0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a  value of the P.*
23dc0 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69  * parameter if i
23dd0 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55  t exists or a NU
23de0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20  LL pointer if P 
23df0 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
23e00 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70  as a .** query p
23e10 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20  arameter on F.  
23e20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20  If P is a query 
23e30 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a  parameter of F.*
23e40 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69  * has no explici
23e50 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71  t value, then sq
23e60 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
23e70 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
23e80 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
23e90 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
23ea0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
23eb0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
23ec0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61  F,P,B) routine a
23ed0 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73  ssumes that P is
23ee0 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61   a boolean.** pa
23ef0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
23f00 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20  rns true (1) or 
23f10 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64  false (0) accord
23f20 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ing to the value
23f30 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73  .** of P.  The s
23f40 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
23f50 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
23f60 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
23f70 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c  1) if the.** val
23f80 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61  ue of query para
23f90 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
23fa0 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c  f "yes", "true",
23fb0 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a   or "on" in any.
23fc0 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68  ** case or if th
23fd0 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
23fe0 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e  ith a non-zero n
23ff0 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20  umber.  The .** 
24000 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
24010 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
24020 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73  nes returns fals
24030 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c  e (0) if the val
24040 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70  ue of.** query p
24050 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
24060 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73  e of "no", "fals
24070 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20  e", or "off" in 
24080 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69  any case or.** i
24090 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
240a0 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69  ns with a numeri
240b0 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73  c zero.  If P is
240c0 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20   not a query.** 
240d0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f  parameter on F o
240e0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  r if the value o
240f0 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20  f P is does not 
24100 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65  match any of the
24110 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20  .** above, then 
24120 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
24130 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
24140 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a  ns (B!=0)..**.**
24150 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
24160 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f  _int64(F,P,D) ro
24170 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74  utine converts t
24180 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e  he value of P in
24190 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73  to a.** 64-bit s
241a0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
241b0 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69  d returns that i
241c0 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20  nteger, or D if 
241d0 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78  P does not.** ex
241e0 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c  ist.  If the val
241f0 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74  ue of P is somet
24200 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
24210 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e  an integer, then
24220 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75  .** zero is retu
24230 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rned..** .** If 
24240 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  F is a NULL poin
24250 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ter, then sqlite
24260 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
24270 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  F,P) returns NUL
24280 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  L and.** sqlite3
24290 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
242a0 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20  ,B) returns B.  
242b0 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55  If F is not a NU
242c0 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a  LL pointer and.*
242d0 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  * is not a datab
242e0 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  ase file pathnam
242f0 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53  e pointer that S
24300 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74  QLite passed int
24310 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56  o the xOpen.** V
24320 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  FS method, then 
24330 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
24340 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
24350 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
24360 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69  obably.** undesi
24370 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  rable..*/.const 
24380 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72  char *sqlite3_ur
24390 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73  i_parameter(cons
243a0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
243b0 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
243c0 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69  Param);.int sqli
243d0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
243e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
243f0 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
24400 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
24410 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ult);.sqlite3_in
24420 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  t64 sqlite3_uri_
24430 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72  int64(const char
24440 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
24450 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
24460 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24470 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
24480 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
24490 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
244a0 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
244b0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
244c0 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
244d0 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
244e0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
244f0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
24500 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
24510 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
24520 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
24530 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
24540 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
24550 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
24560 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
24570 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
24580 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
24590 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
245a0 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
245b0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
245c0 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  ndefined.  ^The 
245d0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
245e0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
245f0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
24600 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
24610 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
24620 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
24630 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
24640 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
24650 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
24660 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
24670 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
24680 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
24690 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
246a0 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
246b0 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
246c0 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
246d0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
246e0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
246f0 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
24700 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
24710 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
24720 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
24730 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
24740 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
24750 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
24760 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
24770 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
24780 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
24790 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
247a0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
247b0 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
247c0 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
247d0 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
247e0 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
247f0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
24800 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
24810 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24820 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66  _errstr() interf
24830 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
24840 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
24850 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65   text.** that de
24860 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73  scribes the [res
24870 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54  ult code], as UT
24880 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  F-8..** ^(Memory
24890 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
248a0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
248b0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
248c0 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d  ernally.** and m
248d0 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64  ust not be freed
248e0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
248f0 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ion)^..**.** Whe
24900 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
24910 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
24920 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
24930 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
24940 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
24950 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
24960 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
24970 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
24980 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
24990 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
249a0 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
249b0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
249c0 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
249d0 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
249e0 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
249f0 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
24a00 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
24a10 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
24a20 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
24a30 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
24a40 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
24a50 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
24a60 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
24a70 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
24a80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
24a90 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
24aa0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
24ab0 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
24ac0 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
24ad0 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
24ae0 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
24af0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
24b00 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
24b10 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
24b20 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
24b30 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
24b40 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
24b50 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
24b60 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
24b70 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
24b80 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
24b90 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
24ba0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
24bb0 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
24bc0 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
24bd0 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
24be0 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
24bf0 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
24c00 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
24c10 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
24c20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
24c30 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
24c40 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
24c50 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
24c60 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
24c70 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
24c80 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
24c90 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
24ca0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
24cb0 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  6(sqlite3*);.con
24cc0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
24cd0 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
24ce0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
24cf0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
24d00 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
24d10 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
24d20 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
24d30 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
24d40 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
24d50 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
24d60 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
24d70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
24d80 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
24d90 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
24da0 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
24db0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
24dc0 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
24dd0 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
24de0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
24df0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
24e00 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
24e10 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
24e20 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
24e30 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
24e40 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
24e50 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
24e60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
24e70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
24e80 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
24e90 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
24ea0 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
24eb0 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
24ec0 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
24ed0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
24ee0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
24ef0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
24f00 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
24f10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24f20 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
24f30 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
24f40 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
24f50 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
24f60 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
24f70 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
24f80 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
24f90 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
24fa0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
24fb0 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
24fc0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
24fd0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
24fe0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
24ff0 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
25000 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
25010 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
25020 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
25030 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
25040 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
25050 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
25060 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
25070 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
25080 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
25090 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
250a0 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
250b0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
250c0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
250d0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
250e0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
250f0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
25100 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
25110 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
25120 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25130 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
25140 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
25150 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
25160 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
25170 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
25180 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
25190 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
251a0 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
251b0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
251c0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
251d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
251e0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
251f0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
25200 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
25210 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
25220 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
25230 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
25240 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
25250 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
25260 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
25270 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
25280 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
25290 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
252a0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
252b0 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
252c0 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
252d0 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
252e0 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
252f0 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
25300 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
25310 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
25320 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
25330 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
25340 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
25350 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
25360 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
25370 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
25380 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
25390 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
253a0 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
253b0 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
253c0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
253d0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
253e0 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
253f0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
25400 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
25410 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
25420 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
25430 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
25440 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
25450 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
25460 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
25470 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
25480 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
25490 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
254a0 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
254b0 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
254c0 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
254d0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
254e0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
254f0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
25500 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
25510 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
25520 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
25530 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
25540 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
25550 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
25560 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
25570 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
25580 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
25590 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
255a0 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
255b0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
255c0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
255d0 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
255e0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
255f0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
25600 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
25610 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
25620 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
25630 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
25640 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
25650 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
25660 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
25670 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
25680 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
25690 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
256a0 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
256b0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
256c0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
256d0 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
256e0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
256f0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
25700 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
25710 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
25720 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
25730 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
25740 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
25750 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
25760 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
25770 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
25780 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
25790 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
257a0 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
257b0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
257c0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
257d0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
257e0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
257f0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
25800 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
25810 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
25820 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
25830 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
25840 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
25850 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
25860 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
25870 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
25880 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
25890 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
258a0 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
258b0 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
258c0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
258d0 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
258e0 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
258f0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
25900 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
25910 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
25920 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
25930 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
25940 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
25950 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
25960 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
25970 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
25980 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
25990 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
259a0 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
259b0 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
259c0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
259d0 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
259e0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
259f0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
25a00 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
25a10 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
25a20 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
25a30 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
25a40 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
25a50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
25a60 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
25a70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
25a80 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
25a90 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25aa0 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
25ab0 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
25ac0 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
25ad0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25ae0 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
25af0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
25b00 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
25b10 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
25b20 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
25b30 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
25b40 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
25b50 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
25b60 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
25b70 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
25b80 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
25b90 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
25ba0 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
25bb0 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
25bc0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
25bd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
25be0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
25bf0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
25c00 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
25c10 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25c20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
25c30 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
25c40 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
25c50 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
25c60 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
25c70 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
25c80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
25c90 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
25ca0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25cb0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
25cc0 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
25cd0 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
25ce0 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
25cf0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25d00 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
25d10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
25d20 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
25d30 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
25d40 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
25d50 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
25d60 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
25d70 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
25d80 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
25d90 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69  tement.  This li
25da0 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  mit is not curre
25db0 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64  ntly.** enforced
25dc0 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69  , though that mi
25dd0 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20  ght be added in 
25de0 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
25df0 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
25e00 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
25e10 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
25e20 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c  NCTION_ARG]] ^(<
25e30 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25e40 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
25e50 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25e60 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
25e70 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
25e80 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
25e90 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25ea0 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e  MIT_ATTACHED]] ^
25eb0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25ec0 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
25ed0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25ee0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
25ef0 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
25f00 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
25f10 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
25f20 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
25f30 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a  TERN_LENGTH]].**
25f40 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25f50 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
25f60 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
25f70 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25f80 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
25f90 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
25fa0 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
25fb0 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
25fc0 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
25fd0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25fe0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
25ff0 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
26000 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
26010 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
26020 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
26030 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
26040 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
26050 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
26060 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ment.)^.**.** [[
26070 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
26080 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  GGER_DEPTH]] ^(<
26090 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
260a0 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
260b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
260c0 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
260d0 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
260e0 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
260f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
26100 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
26110 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  S]] ^(<dt>SQLITE
26120 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
26130 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  READS</dt>.** <d
26140 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
26150 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72  mber of auxiliar
26160 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73  y worker threads
26170 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a   that a single.*
26180 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
26190 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74  ement] may start
261a0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
261b0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
261c0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
261d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
261e0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
261f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
26200 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
26210 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
26220 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
26230 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
26240 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
26250 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
26260 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
26270 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
26280 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
26290 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
262a0 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
262b0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
262c0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
262d0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
262e0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
262f0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
26300 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
26310 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26320 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
26330 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
26340 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26350 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
26360 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
26370 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26380 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
26390 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
263a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
263b0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
263c0 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
263d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
263e0 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
263f0 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31  ADS           11
26400 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26410 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
26420 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
26430 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
26440 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
26450 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
26460 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
26470 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
26480 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
26490 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
264a0 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
264b0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
264c0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
264d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
264e0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
264f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
26500 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
26510 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
26520 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
26530 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
26540 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26550 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
26560 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
26570 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26580 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
26590 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
265a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
265b0 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
265c0 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
265d0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
265e0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
265f0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
26600 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
26610 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
26620 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
26630 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
26640 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
26650 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
26660 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
26670 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
26680 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
26690 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
266a0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
266b0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
266c0 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
266d0 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
266e0 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
266f0 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
26700 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
26710 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
26720 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
26730 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
26740 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
26750 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
26760 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
26770 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
26780 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
26790 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
267a0 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
267b0 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
267c0 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
267d0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
267e0 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
267f0 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
26800 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
26810 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
26820 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
26830 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
26840 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
26850 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
26860 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
26870 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
26880 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
26890 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
268a0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
268b0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
268c0 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
268d0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
268e0 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73  minator bytes as
268f0 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69   this saves SQLi
26900 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74  te from having t
26910 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79  o.** make a copy
26920 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   of the input st
26930 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
26940 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
26950 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
26960 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
26970 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
26980 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
26990 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
269a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
269b0 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
269c0 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
269d0 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
269e0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
269f0 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
26a00 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
26a10 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
26a20 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
26a30 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
26a40 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
26a50 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
26a60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26a70 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
26a80 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
26a90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
26aa0 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
26ab0 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
26ac0 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
26ad0 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
26ae0 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
26af0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
26b00 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
26b10 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
26b20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
26b30 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
26b40 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
26b50 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
26b60 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
26b70 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
26b80 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
26b90 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
26ba0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
26bb0 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
26bc0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
26bd0 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
26be0 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
26bf0 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
26c00 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
26c10 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
26c20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
26c30 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
26c40 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
26c50 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
26c60 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
26c70 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
26c80 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
26c90 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
26ca0 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
26cb0 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
26cc0 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
26cd0 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
26ce0 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
26cf0 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
26d00 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
26d10 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
26d20 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
26d30 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
26d40 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
26d50 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
26d60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
26d70 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
26d80 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
26d90 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
26da0 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
26db0 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
26dc0 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
26dd0 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
26de0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
26df0 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
26e00 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
26e10 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
26e20 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
26e30 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
26e40 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
26e50 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
26e60 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
26e70 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
26e80 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
26e90 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
26ea0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
26eb0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
26ec0 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
26ed0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
26ee0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
26ef0 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53  n. As many as [S
26f00 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41  QLITE_MAX_SCHEMA
26f10 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69  _RETRY].** retri
26f20 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65  es will occur be
26f30 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65  fore sqlite3_ste
26f40 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64  p() gives up and
26f50 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
26f60 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  r..** </li>.**.*
26f70 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
26f80 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
26f90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
26fa0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
26fb0 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
26fc0 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
26fd0 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
26fe0 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
26ff0 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
27000 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
27010 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
27020 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
27030 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
27040 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
27050 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
27060 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
27070 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
27080 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
27090 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
270a0 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
270b0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
270c0 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
270d0 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
270e0 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
270f0 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
27100 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
27110 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
27120 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
27130 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
27140 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
27150 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
27160 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
27170 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
27180 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
27190 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
271a0 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
271b0 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
271c0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
271d0 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
271e0 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
271f0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
27200 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
27210 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
27220 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
27230 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
27240 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
27250 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
27260 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
27270 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
27280 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
27290 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
272a0 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
272b0 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
272c0 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
272d0 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
272e0 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
272f0 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
27300 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
27310 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
27320 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
27330 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
27340 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
27350 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
27360 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
27370 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
27380 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
27390 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
273a0 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
273b0 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
273c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
273d0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
273e0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
273f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
27400 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
27410 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
27420 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
27430 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
27440 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
27450 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
27460 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
27470 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
27480 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
27490 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
274a0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
274b0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
274c0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
274d0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
274e0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
274f0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
27500 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
27510 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
27520 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
27530 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
27540 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
27550 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
27560 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
27570 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
27580 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
27590 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
275a0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
275b0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
275c0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
275d0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
275e0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
275f0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
27600 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
27610 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
27620 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
27630 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
27640 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
27650 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
27660 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
27670 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
27680 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27690 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
276a0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
276b0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
276c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
276d0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
276e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
276f0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
27700 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
27710 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
27720 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
27730 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
27740 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
27750 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
27760 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
27770 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
27780 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
27790 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
277a0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
277b0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
277c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
277d0 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
277e0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
277f0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
27800 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
27810 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
27820 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
27830 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
27840 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
27850 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
27860 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
27870 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
27880 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
27890 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
278a0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
278b0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
278c0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
278d0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
278e0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
278f0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
27900 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
27910 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
27920 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
27930 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  t SQL.**.** ^Thi
27940 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
27950 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
27960 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
27970 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
27980 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
27990 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
279a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
279b0 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
279c0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
279d0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
279e0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
279f0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
27a00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
27a10 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  2()]..*/.const c
27a20 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
27a30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
27a40 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
27a50 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
27a60 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
27a70 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
27a80 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20   Database.**.** 
27a90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
27aa0 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e  t_readonly(X) in
27ab0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27ac0 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
27ad0 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69  if.** and only i
27ae0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
27af0 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b  statement] X mak
27b00 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61  es no direct cha
27b10 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63  nges to.** the c
27b20 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
27b30 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
27b40 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70  ** Note that [ap
27b50 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
27b60 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
27b70 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20   or.** [virtual 
27b80 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68  tables] might ch
27b90 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
27ba0 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20  e indirectly as 
27bb0 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20  a side effect.  
27bc0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
27bd0 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  e, if an applica
27be0 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66  tion defines a f
27bf0 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22  unction "eval()"
27c00 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20   that .** calls 
27c10 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
27c20 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f  , then the follo
27c30 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  wing SQL stateme
27c40 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e  nt would.** chan
27c50 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
27c60 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64  file through sid
27c70 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a  e-effects:.**.**
27c80 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
27c90 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20  e>.**    SELECT 
27ca0 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f  eval('DELETE FRO
27cb0 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a  M t1') FROM t2;.
27cc0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
27cd0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74  quote>.**.** But
27ce0 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45   because the [SE
27cf0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
27d00 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
27d10 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
27d20 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73  e.** directly, s
27d30 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
27d40 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69  only() would sti
27d50 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29  ll return true.)
27d60 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63  ^.**.** ^Transac
27d70 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61  tion control sta
27d80 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20  tements such as 
27d90 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54  [BEGIN], [COMMIT
27da0 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a  ], [ROLLBACK],.*
27db0 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61  * [SAVEPOINT], a
27dc0 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75  nd [RELEASE] cau
27dd0 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  se sqlite3_stmt_
27de0 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
27df0 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69  turn true,.** si
27e00 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  nce the statemen
27e10 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f  ts themselves do
27e20 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f   not actually mo
27e30 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
27e40 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20  e but.** rather 
27e50 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65  they control the
27e60 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20   timing of when 
27e70 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73  other statements
27e80 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20   modify the .** 
27e90 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20  database.  ^The 
27ea0 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45  [ATTACH] and [DE
27eb0 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73  TACH] statements
27ec0 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73   also cause.** s
27ed0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
27ee0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
27ef0 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69   true since, whi
27f00 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65  le those stateme
27f10 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  nts.** change th
27f20 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
27f30 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  of a database co
27f40 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64  nnection, they d
27f50 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63  o not make .** c
27f60 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f  hanges to the co
27f70 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
27f80 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64  abase files on d
27f90 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  isk..*/.int sqli
27fa0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
27fb0 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
27fc0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
27fd0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
27fe0 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64  ne If A Prepared
27ff0 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42   Statement Has B
28000 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20  een Reset.**.** 
28010 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
28020 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66  t_busy(S) interf
28030 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
28040 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74   (non-zero) if t
28050 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
28060 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73  statement] S has
28070 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74   been stepped at
28080 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e   least once usin
28090 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  g .** [sqlite3_s
280a0 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20  tep(S)] but has 
280b0 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c  not run to compl
280c0 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73  etion and/or has
280d0 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65   not .** been re
280e0 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  set using [sqlit
280f0 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e  e3_reset(S)].  ^
28100 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
28110 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65  _busy(S).** inte
28120 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61  rface returns fa
28130 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55  lse if S is a NU
28140 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
28150 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e  S is not a .** N
28160 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ULL pointer and 
28170 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72  is not a pointer
28180 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65   to a valid [pre
28190 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
281a0 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e  .** object, then
281b0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
281c0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
281d0 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
281e0 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ble..**.** This 
281f0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
28200 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61   used in combina
28210 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65  tion [sqlite3_ne
28220 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f  xt_stmt()].** to
28230 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70   locate all prep
28240 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20  ared statements 
28250 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
28260 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63  a database .** c
28270 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61  onnection that a
28280 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65  re in need of be
28290 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73  ing reset.  This
282a0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a   can be used,.**
282b0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e   for example, in
282c0 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74   diagnostic rout
282d0 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66  ines to search f
282e0 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20  or prepared .** 
282f0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
28300 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72  are holding a tr
28310 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a  ansaction open..
28320 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
28330 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
28340 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
28350 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
28360 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
28370 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
28380 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
28390 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
283a0 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
283b0 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
283c0 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
283d0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
283e0 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
283f0 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
28400 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
28410 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
28420 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
28430 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
28440 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
28450 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
28460 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
28470 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
28480 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
28490 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
284a0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
284b0 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
284c0 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
284d0 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
284e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
284f0 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
28500 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
28510 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
28520 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
28530 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
28540 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
28550 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
28560 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
28570 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
28580 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
28590 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
285a0 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
285b0 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
285c0 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
285d0 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
285e0 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
285f0 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
28600 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
28610 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
28620 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
28630 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
28640 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
28650 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
28660 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
28670 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
28680 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
28690 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
286a0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
286b0 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
286c0 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
286d0 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
286e0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
286f0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
28700 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
28710 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
28720 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
28730 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
28740 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
28750 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
28760 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
28770 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
28780 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
28790 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
287a0 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
287b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
287c0 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
287d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
287e0 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
287f0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
28800 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
28810 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
28820 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
28830 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28840 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
28850 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
28860 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
28870 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
28880 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
28890 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
288a0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
288b0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
288c0 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
288d0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
288e0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
288f0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
28900 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28910 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
28920 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
28930 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
28940 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28950 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
28960 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
28970 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
28980 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
28990 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
289a0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
289b0 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
289c0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
289d0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
289e0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
289f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
28a00 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
28a10 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
28a20 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28a30 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
28a40 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
28a50 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
28a60 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
28a70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
28a80 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
28a90 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
28aa0 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
28ab0 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
28ac0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
28ad0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
28ae0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28af0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
28b00 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
28b10 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
28b20 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
28b30 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
28b40 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
28b50 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
28b60 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
28b70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
28b80 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
28b90 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
28ba0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
28bb0 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
28bc0 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
28bd0 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
28be0 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
28bf0 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
28c00 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
28c10 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
28c20 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
28c30 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
28c40 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
28c50 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
28c60 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
28c70 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
28c80 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
28c90 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
28ca0 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
28cb0 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
28cc0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
28cd0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
28ce0 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
28cf0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
28d00 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
28d10 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
28d20 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
28d30 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
28d40 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
28d50 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
28d60 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
28d70 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
28d80 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
28d90 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
28da0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
28db0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
28dc0 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
28dd0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
28de0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
28df0 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
28e00 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
28e10 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
28e20 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
28e30 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28  inding}.**.** ^(
28e40 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
28e50 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
28e60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
28e70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
28e80 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
28e90 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
28ea0 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
28eb0 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
28ec0 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
28ed0 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
28ee0 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
28ef0 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
28f00 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
28f10 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
28f20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
28f30 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
28f40 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
28f50 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
28f60 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
28f70 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
28f80 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
28f90 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
28fa0 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
28fb0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
28fc0 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
28fd0 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
28fe0 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
28ff0 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
29000 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
29010 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
29020 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
29030 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
29040 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
29050 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
29060 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
29070 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
29080 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
29090 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
290a0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
290b0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
290c0 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
290d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
290e0 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
290f0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
29100 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
29110 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
29120 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
29130 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
29140 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
29150 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
29160 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
29170 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
29180 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
29190 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
291a0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
291b0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
291c0 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
291d0 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
291e0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
291f0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
29200 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
29210 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
29220 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
29230 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
29240 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
29250 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
29260 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
29270 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
29280 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
29290 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
292a0 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
292b0 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
292c0 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
292d0 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
292e0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
292f0 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
29300 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
29310 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
29320 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
29330 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
29340 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
29350 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
29360 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
29370 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
29380 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
29390 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
293a0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
293b0 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73  text16().** or s
293c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
293d0 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
293e0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f  nter then the fo
293f0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a  urth parameter.*
29400 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64  * is ignored and
29410 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20   the end result 
29420 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73  is the same as s
29430 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
29440 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ()..**.** ^(In t
29450 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
29460 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
29470 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
29480 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
29490 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
294a0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
294b0 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
294c0 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
294d0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
294e0 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
294f0 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
29500 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
29510 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
29520 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
29530 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
29540 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
29550 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
29560 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
29570 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
29580 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
29590 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
295a0 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
295b0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
295c0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
295d0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
295e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
295f0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
29600 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
29610 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
29620 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
29630 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
29640 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
29650 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
29660 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
29670 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
29680 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
29690 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  6() or sqlite3_b
296a0 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65  ind_text64() the
296b0 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65  n.** that parame
296c0 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
296d0 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
296e0 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
296f0 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
29700 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
29710 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
29720 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
29730 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
29740 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
29750 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
29760 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
29770 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
29780 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
29790 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
297a0 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
297b0 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
297c0 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
297d0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
297e0 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
297f0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
29800 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
29810 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
29820 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
29830 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c  gument to the BL
29840 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69  OB and string bi
29850 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  nding interfaces
29860 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63  .** is a destruc
29870 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
29880 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
29890 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
298a0 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
298b0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
298c0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
298d0 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
298e0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
298f0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
29900 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
29910 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c  to bind API fail
29920 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  s..** ^If the fi
29930 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
29940 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
29950 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
29960 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
29970 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
29980 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
29990 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
299a0 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
299b0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
299c0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
299d0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
299e0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
299f0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
29a00 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
29a10 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
29a20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
29a30 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
29a40 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
29a50 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
29a60 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
29a70 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
29a80 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61  .** ^The sixth a
29a90 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
29aa0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
29ab0 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a   must be one of.
29ac0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ** [SQLITE_UTF8]
29ad0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  , [SQLITE_UTF16]
29ae0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
29af0 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
29b00 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70  TF16LE].** to sp
29b10 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69  ecify the encodi
29b20 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69  ng of the text i
29b30 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
29b40 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68  meter.  If.** th
29b50 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
29b60 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
29b70 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74  _text64() is not
29b80 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61   one of the.** a
29b90 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68  llowed values sh
29ba0 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66  own above, or if
29bb0 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
29bc0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a  ng is different.
29bd0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f  ** from the enco
29be0 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62  ding specified b
29bf0 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61  y the sixth para
29c00 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
29c10 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
29c20 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
29c30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
29c40 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
29c50 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
29c60 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
29c70 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
29c80 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
29c90 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
29ca0 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
29cb0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
29cc0 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
29cd0 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
29ce0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
29cf0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
29d00 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
29d10 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
29d20 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
29d30 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
29d40 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
29d50 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
29d60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
29d70 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
29d80 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
29d90 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
29da0 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
29db0 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
29dc0 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
29dd0 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
29de0 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
29df0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
29e00 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
29e10 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
29e20 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
29e30 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
29e40 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
29e50 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
29e60 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
29e70 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
29e80 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
29e90 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
29ea0 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
29eb0 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
29ec0 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
29ed0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
29ee0 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
29ef0 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
29f00 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
29f10 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
29f20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
29f30 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
29f40 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
29f50 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
29f60 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
29f70 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
29f80 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
29f90 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
29fa0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29fb0 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
29fc0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
29fd0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
29fe0 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
29ff0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2a000 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
2a010 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
2a020 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
2a030 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
2a040 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
2a050 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
2a060 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67  LITE_TOOBIG] mig
2a070 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
2a080 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  f the size of a 
2a090 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a  string or BLOB.*
2a0a0 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73  * exceeds limits
2a0b0 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c   imposed by [sql
2a0c0 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
2a0d0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2a0e0 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  ]) or.** [SQLITE
2a0f0 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a  _MAX_LENGTH]..**
2a100 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
2a110 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2a120 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
2a130 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2a140 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
2a150 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
2a160 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
2a170 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
2a180 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2a190 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2a1a0 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
2a1b0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2a1c0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2a1d0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
2a1e0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2a1f0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2a200 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
2a210 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2a220 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2a230 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
2a240 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2a250 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71  3_bind_blob64(sq
2a260 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a270 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73  , const void*, s
2a280 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
2a290 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a2a0 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
2a2b0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2a2c0 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
2a2d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a2e0 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
2a2f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
2a300 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2a310 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
2a320 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2a330 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2a340 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
2a350 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
2a360 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
2a370 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
2a380 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2a390 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
2a3a0 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  stmt*,int,const 
2a3b0 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a  char*,int,void(*
2a3c0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2a3d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2a3e0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2a3f0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2a400 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
2a410 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2a420 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2a430 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2a440 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
2a450 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
2a460 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
2a470 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2a480 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69  (*)(void*), unsi
2a490 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69  gned char encodi
2a4a0 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ng);.int sqlite3
2a4b0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
2a4c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2a4d0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
2a4e0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2a4f0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2a500 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a510 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
2a520 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2a530 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
2a540 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
2a550 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
2a560 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
2a570 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
2a580 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
2a590 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
2a5a0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
2a5b0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2a5c0 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
2a5d0 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
2a5e0 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
2a5f0 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
2a600 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
2a610 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
2a620 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
2a630 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2a640 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
2a650 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
2a660 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
2a670 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
2a680 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
2a690 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
2a6a0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
2a6b0 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
2a6c0 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
2a6d0 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
2a6e0 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
2a6f0 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
2a700 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
2a710 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
2a720 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
2a730 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
2a740 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
2a750 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
2a760 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
2a770 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2a780 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2a790 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2a7a0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2a7b0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2a7c0 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
2a7d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2a7e0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2a7f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2a800 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2a810 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2a820 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2a830 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
2a840 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
2a850 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2a860 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2a870 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
2a880 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
2a890 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
2a8a0 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
2a8b0 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
2a8c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a8d0 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
2a8e0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
2a8f0 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
2a900 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2a910 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
2a920 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
2a930 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
2a940 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2a950 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2a960 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
2a970 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2a980 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
2a990 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
2a9a0 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
2a9b0 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
2a9c0 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
2a9d0 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
2a9e0 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
2a9f0 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
2aa00 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
2aa10 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
2aa20 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
2aa30 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
2aa40 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
2aa50 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
2aa60 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
2aa70 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2aa80 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
2aa90 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
2aaa0 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
2aab0 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
2aac0 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
2aad0 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
2aae0 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
2aaf0 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
2ab00 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
2ab10 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
2ab20 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
2ab30 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
2ab40 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
2ab50 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
2ab60 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
2ab70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ab80 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
2ab90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2aba0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2abb0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2abc0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2abd0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2abe0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2abf0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2ac00 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2ac10 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2ac20 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
2ac30 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2ac40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2ac50 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2ac60 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
2ac70 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
2ac80 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
2ac90 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
2aca0 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2acb0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
2acc0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
2acd0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
2ace0 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
2acf0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
2ad00 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
2ad10 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
2ad20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2ad30 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2ad40 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
2ad50 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
2ad60 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
2ad70 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
2ad80 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
2ad90 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
2ada0 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
2adb0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
2adc0 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
2add0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
2ade0 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
2adf0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
2ae00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ae10 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2ae20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2ae30 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2ae40 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2ae50 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2ae60 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2ae70 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2ae80 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2ae90 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2aea0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2aeb0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2aec0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2aed0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2aee0 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
2aef0 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
2af00 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
2af10 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
2af20 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
2af30 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
2af40 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
2af50 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
2af60 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
2af70 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2af80 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
2af90 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2afa0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2afb0 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
2afc0 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
2afd0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
2afe0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
2aff0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
2b000 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
2b010 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2b020 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
2b030 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
2b040 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
2b050 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
2b060 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2b070 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
2b080 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2b090 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b0a0 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
2b0b0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2b0c0 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
2b0d0 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
2b0e0 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
2b0f0 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
2b100 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
2b110 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
2b120 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
2b130 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
2b140 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2b150 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2b160 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2b170 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2b180 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
2b190 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
2b1a0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2b1b0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2b1c0 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
2b1d0 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
2b1e0 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
2b1f0 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
2b200 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
2b210 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2b220 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
2b230 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b240 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2b250 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2b260 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
2b270 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2b280 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
2b290 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2b2a0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2b2b0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
2b2c0 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
2b2d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2b2e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b2f0 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
2b300 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
2b310 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2b320 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
2b330 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
2b340 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
2b350 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2b360 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
2b370 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
2b380 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
2b390 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
2b3a0 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
2b3b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b3c0 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
2b3d0 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
2b3e0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2b3f0 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2b400 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2b410 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2b420 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2b430 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2b440 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2b450 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2b460 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
2b470 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
2b480 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2b490 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
2b4a0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
2b4b0 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
2b4c0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
2b4d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
2b4e0 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
2b4f0 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
2b500 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
2b510 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
2b520 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
2b530 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
2b540 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
2b550 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2b560 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2b570 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
2b580 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
2b590 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2b5a0 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
2b5b0 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
2b5c0 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
2b5d0 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
2b5e0 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
2b5f0 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
2b600 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
2b610 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
2b620 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
2b630 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
2b640 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
2b650 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
2b660 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2b670 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2b680 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b690 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
2b6a0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2b6b0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2b6c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
2b6d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b6e0 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
2b6f0 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
2b700 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2b710 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
2b720 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
2b730 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
2b740 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
2b750 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
2b760 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
2b770 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
2b780 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2b790 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
2b7a0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
2b7b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
2b7c0 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
2b7d0 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
2b7e0 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
2b7f0 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
2b800 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2b810 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
2b820 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2b830 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2b840 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
2b850 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2b860 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
2b870 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
2b880 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
2b890 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
2b8a0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
2b8b0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2b8c0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
2b8d0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2b8e0 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
2b8f0 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
2b900 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2b910 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
2b920 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
2b930 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
2b940 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
2b950 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
2b960 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
2b970 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
2b980 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
2b990 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
2b9a0 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
2b9b0 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
2b9c0 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
2b9d0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
2b9e0 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
2b9f0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
2ba00 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
2ba10 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
2ba20 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
2ba30 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
2ba40 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2ba50 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
2ba60 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
2ba70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2ba80 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
2ba90 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
2baa0 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
2bab0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
2bac0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
2bad0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
2bae0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
2baf0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
2bb00 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
2bb10 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
2bb20 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
2bb30 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
2bb40 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2bb50 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
2bb60 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
2bb70 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
2bb80 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
2bb90 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
2bba0 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
2bbb0 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
2bbc0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2bbd0 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
2bbe0 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
2bbf0 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
2bc00 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
2bc10 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
2bc20 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
2bc30 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
2bc40 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
2bc50 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
2bc60 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
2bc70 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
2bc80 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
2bc90 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
2bca0 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
2bcb0 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
2bcc0 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
2bcd0 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
2bce0 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
2bcf0 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
2bd00 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
2bd10 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
2bd20 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
2bd30 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
2bd40 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
2bd50 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
2bd60 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
2bd70 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
2bd80 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
2bd90 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
2bda0 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
2bdb0 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
2bdc0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2bdd0 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2bde0 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
2bdf0 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
2be00 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
2be10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2be20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
2be30 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2be40 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2be50 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2be60 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2be70 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2be80 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
2be90 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2bea0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
2beb0 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
2bec0 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
2bed0 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
2bee0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2bef0 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
2bf00 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
2bf10 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2bf20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2bf30 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
2bf40 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2bf50 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2bf60 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2bf70 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2bf80 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2bf90 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
2bfa0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2bfb0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
2bfc0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2bfd0 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
2bfe0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2bff0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2c000 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2c010 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2c020 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2c030 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2c040 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2c050 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2c060 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2c070 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2c080 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
2c090 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2c0a0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2c0b0 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
2c0c0 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
2c0d0 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
2c0e0 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
2c0f0 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
2c100 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2c110 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
2c120 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
2c130 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
2c140 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2c150 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
2c160 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
2c170 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
2c180 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
2c190 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
2c1a0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2c1b0 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
2c1c0 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
2c1d0 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
2c1e0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
2c1f0 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
2c200 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2c210 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
2c220 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2c230 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
2c240 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2c250 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
2c260 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2c270 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
2c280 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
2c290 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
2c2a0 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
2c2b0 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
2c2c0 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
2c2d0 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
2c2e0 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
2c2f0 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
2c300 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
2c310 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
2c320 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
2c330 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
2c340 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
2c350 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
2c360 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
2c370 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
2c380 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
2c390 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2c3a0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
2c3b0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
2c3c0 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
2c3d0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2c3e0 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
2c3f0 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
2c400 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
2c410 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
2c420 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
2c430 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
2c440 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
2c450 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
2c460 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
2c470 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
2c480 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
2c490 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
2c4a0 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
2c4b0 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
2c4c0 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
2c4d0 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
2c4e0 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
2c4f0 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
2c500 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
2c510 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
2c520 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
2c530 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2c540 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2c550 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
2c560 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2c570 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2c580 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
2c590 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2c5a0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2c5b0 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
2c5c0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2c5d0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
2c5e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c5f0 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
2c600 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
2c610 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
2c620 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2c630 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c640 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
2c650 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
2c660 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
2c670 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2c680 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2c690 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
2c6a0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
2c6b0 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
2c6c0 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
2c6d0 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
2c6e0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
2c6f0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
2c700 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
2c710 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2c720 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
2c730 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
2c740 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2c750 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
2c760 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
2c770 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
2c780 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2c790 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2c7a0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2c7b0 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
2c7c0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2c7d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c7e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2c7f0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
2c800 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
2c810 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
2c820 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2c830 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
2c840 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
2c850 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2c860 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
2c870 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
2c880 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
2c890 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2c8a0 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
2c8b0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
2c8c0 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
2c8d0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
2c8e0 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
2c8f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
2c900 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
2c910 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
2c920 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2c930 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
2c940 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
2c950 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
2c960 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2c970 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2c980 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
2c990 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
2c9a0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2c9b0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2c9c0 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
2c9d0 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
2c9e0 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
2c9f0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
2ca00 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
2ca10 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
2ca20 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
2ca30 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
2ca40 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2ca50 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
2ca60 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
2ca70 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
2ca80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2ca90 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
2caa0 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
2cab0 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
2cac0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
2cad0 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
2cae0 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
2caf0 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
2cb00 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
2cb10 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
2cb20 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2cb30 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
2cb40 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
2cb50 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2cb60 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2cb70 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2cb80 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
2cb90 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
2cba0 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
2cbb0 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
2cbc0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2cbd0 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
2cbe0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2cbf0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2cc00 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
2cc10 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
2cc20 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
2cc30 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
2cc40 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
2cc50 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
2cc60 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
2cc70 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
2cc80 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
2cc90 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
2cca0 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
2ccb0 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
2ccc0 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
2ccd0 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
2cce0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
2ccf0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2cd00 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
2cd10 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
2cd20 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
2cd30 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
2cd40 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
2cd50 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
2cd60 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
2cd70 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
2cd80 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
2cd90 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
2cda0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2cdb0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2cdc0 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
2cdd0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
2cde0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
2cdf0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2ce00 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
2ce10 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
2ce20 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
2ce30 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2ce40 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
2ce50 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
2ce60 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
2ce70 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
2ce80 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
2ce90 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
2cea0 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
2ceb0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2cec0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
2ced0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2cee0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
2cef0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2cf00 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
2cf10 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2cf20 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
2cf30 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
2cf40 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
2cf50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
2cf60 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
2cf70 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
2cf80 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
2cf90 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
2cfa0 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
2cfb0 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
2cfc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2cfd0 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
2cfe0 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
2cff0 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2d000 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
2d010 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
2d020 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
2d030 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2d040 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2d050 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
2d060 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
2d070 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
2d080 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2d090 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
2d0a0 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
2d0b0 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
2d0c0 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
2d0d0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
2d0e0 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
2d0f0 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
2d100 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
2d110 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
2d120 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d130 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
2d140 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
2d150 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
2d160 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
2d170 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2d180 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
2d190 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
2d1a0 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
2d1b0 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
2d1c0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
2d1d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d1e0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2d1f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
2d200 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
2d210 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2d220 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
2d230 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2d240 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
2d250 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
2d260 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
2d270 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
2d280 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
2d290 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
2d2a0 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
2d2b0 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
2d2c0 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2d2d0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
2d2e0 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
2d2f0 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
2d300 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
2d310 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
2d320 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
2d330 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
2d340 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
2d350 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
2d360 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
2d370 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
2d380 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
2d390 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
2d3a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
2d3b0 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
2d3c0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2d3d0 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
2d3e0 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
2d3f0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2d400 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
2d410 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
2d420 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2d430 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
2d440 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
2d450 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
2d460 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
2d470 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2d480 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
2d490 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
2d4a0 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
2d4b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2d4c0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2d4d0 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
2d4e0 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
2d4f0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
2d500 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
2d510 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
2d520 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
2d530 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
2d540 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
2d550 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
2d560 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
2d570 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
2d580 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
2d590 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
2d5a0 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
2d5b0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
2d5c0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
2d5d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2d5e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2d5f0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
2d600 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
2d610 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
2d620 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2d630 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2d640 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
2d650 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
2d660 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2d670 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
2d680 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
2d690 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2d6a0 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
2d6b0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2d6c0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2d6d0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2d6e0 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
2d6f0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2d700 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
2d710 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
2d720 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
2d730 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2d740 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
2d750 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2d760 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2d770 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
2d780 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2d790 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
2d7a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d7b0 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
2d7c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2d7d0 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
2d7e0 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
2d7f0 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
2d800 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
2d810 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2d820 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
2d830 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
2d840 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
2d850 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2d860 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
2d870 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2d880 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2d890 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
2d8a0 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
2d8b0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
2d8c0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2d8d0 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2d8e0 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
2d8f0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
2d900 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2d910 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2d920 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
2d930 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
2d940 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
2d950 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
2d960 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
2d970 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2d980 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2d990 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
2d9a0 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
2d9b0 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
2d9c0 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
2d9d0 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
2d9e0 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
2d9f0 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
2da00 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
2da10 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
2da20 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
2da30 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
2da40 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
2da50 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
2da60 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
2da70 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
2da80 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2da90 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2daa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
2dab0 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
2dac0 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2dad0 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
2dae0 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
2daf0 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2db00 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2db10 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2db20 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2db30 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2db40 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2db50 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2db60 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2db70 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2db80 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2db90 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2dba0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
2dbb0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
2dbc0 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
2dbd0 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
2dbe0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2dbf0 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
2dc00 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
2dc10 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
2dc20 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
2dc30 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
2dc40 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
2dc50 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
2dc60 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
2dc70 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
2dc80 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
2dc90 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
2dca0 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
2dcb0 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
2dcc0 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
2dcd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
2dce0 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
2dcf0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
2dd00 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2dd10 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
2dd20 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
2dd30 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
2dd40 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
2dd50 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
2dd60 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
2dd70 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
2dd80 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
2dd90 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
2dda0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ddb0 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
2ddc0 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
2ddd0 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
2dde0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2ddf0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
2de00 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
2de10 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
2de20 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
2de30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2de40 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2de50 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
2de60 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
2de70 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
2de80 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
2de90 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
2dea0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2deb0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
2dec0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
2ded0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2dee0 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
2def0 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
2df00 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
2df10 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2df20 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2df30 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2df40 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
2df50 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
2df60 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2df70 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2df80 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
2df90 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
2dfa0 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
2dfb0 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
2dfc0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
2dfd0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2dfe0 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
2dff0 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
2e000 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2e010 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
2e020 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
2e030 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2e040 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
2e050 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
2e060 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2e070 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
2e080 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
2e090 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
2e0a0 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
2e0b0 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
2e0c0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2e0d0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
2e0e0 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
2e0f0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2e100 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2e110 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2e120 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2e130 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2e140 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
2e150 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
2e160 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
2e170 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2e180 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2e190 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
2e1a0 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
2e1b0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2e1c0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
2e1d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2e1e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2e1f0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
2e200 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
2e210 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
2e220 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
2e230 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2e240 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
2e250 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2e260 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
2e270 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2e280 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2e290 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2e2a0 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
2e2b0 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
2e2c0 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
2e2d0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2e2e0 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
2e2f0 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
2e300 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2e310 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2e320 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2e330 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
2e340 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
2e350 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2e360 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
2e370 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
2e380 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
2e390 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
2e3a0 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
2e3b0 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
2e3c0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
2e3d0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
2e3e0 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2e3f0 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
2e400 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
2e410 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
2e420 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2e430 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e440 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
2e450 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
2e460 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
2e470 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
2e480 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
2e490 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
2e4a0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
2e4b0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
2e4c0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2e4d0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2e4e0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
2e4f0 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
2e500 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
2e510 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
2e520 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
2e530 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
2e540 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
2e550 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
2e560 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2e570 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2e580 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
2e590 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2e5a0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
2e5b0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2e5c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2e5d0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2e5e0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2e5f0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2e600 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
2e610 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2e620 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
2e630 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2e640 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
2e650 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2e660 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2e670 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2e680 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2e690 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2e6a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e6b0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2e6c0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2e6d0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2e6e0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
2e6f0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2e700 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2e710 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2e720 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2e730 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2e740 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2e750 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e760 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2e770 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2e780 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2e790 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
2e7a0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2e7b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2e7c0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2e7d0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2e7e0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2e7f0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2e800 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2e810 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
2e820 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2e830 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2e840 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
2e850 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2e860 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
2e870 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2e880 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2e890 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2e8a0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2e8b0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2e8c0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
2e8d0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2e8e0 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2e8f0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2e900 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
2e910 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2e920 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2e930 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2e940 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2e950 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2e960 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2e970 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2e980 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2e990 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
2e9a0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2e9b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e9c0 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
2e9d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e9e0 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
2e9f0 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
2ea00 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
2ea10 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
2ea20 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
2ea30 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
2ea40 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
2ea50 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2ea60 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
2ea70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ea80 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
2ea90 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
2eaa0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2eab0 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
2eac0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2ead0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
2eae0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2eaf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2eb00 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2eb10 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2eb20 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2eb30 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2eb40 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
2eb50 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
2eb60 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
2eb70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2eb80 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
2eb90 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
2eba0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2ebb0 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
2ebc0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2ebd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2ebe0 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2ebf0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2ec00 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2ec10 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
2ec20 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2ec30 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
2ec40 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
2ec50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2ec60 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2ec70 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2ec80 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2ec90 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2eca0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2ecb0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2ecc0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2ecd0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2ece0 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2ecf0 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2ed00 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2ed10 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2ed20 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2ed30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2ed40 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2ed50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2ed60 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
2ed70 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2ed80 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
2ed90 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2eda0 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2edb0 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2edc0 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
2edd0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
2ede0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
2edf0 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
2ee00 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
2ee10 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
2ee20 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
2ee30 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
2ee40 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
2ee50 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
2ee60 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
2ee70 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
2ee80 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
2ee90 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
2eea0 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
2eeb0 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
2eec0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2eed0 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2eee0 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2eef0 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
2ef00 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
2ef10 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
2ef20 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
2ef30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2ef40 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
2ef50 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
2ef60 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
2ef70 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2ef80 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
2ef90 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
2efa0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2efb0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2efc0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2efd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2efe0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2eff0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2f000 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2f010 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2f020 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2f030 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
2f040 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2f050 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
2f060 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
2f070 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2f080 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2f090 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2f0a0 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
2f0b0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2f0c0 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
2f0d0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2f0e0 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
2f0f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2f100 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
2f110 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2f120 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
2f130 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2f140 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2f150 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2f160 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
2f170 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2f180 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
2f190 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
2f1a0 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c  to BLOB.** <tr><
2f1b0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2f1c0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2f1d0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
2f1e0 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
2f1f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
2f200 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
2f210 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
2f220 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2f230 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2f240 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
2f250 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2f260 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2f270 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2f280 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
2f290 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2f2a0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2f2b0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
2f2c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2f2d0 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
2f2e0 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
2f2f0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2f300 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
2f310 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2f320 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54  quote>)^.**.** T
2f330 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
2f340 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
2f350 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
2f360 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
2f370 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
2f380 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
2f390 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
2f3a0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2f3b0 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
2f3c0 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
2f3d0 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
2f3e0 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
2f3f0 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
2f400 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
2f410 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
2f420 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
2f430 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
2f440 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
2f450 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
2f460 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
2f470 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
2f480 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
2f490 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
2f4a0 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
2f4b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f4c0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
2f4d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
2f4e0 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
2f4f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2f500 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
2f510 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
2f520 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
2f530 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
2f540 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
2f550 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
2f560 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
2f570 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
2f580 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2f590 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
2f5a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f5b0 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
2f5c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f5d0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2f5e0 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
2f5f0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
2f600 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
2f610 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
2f620 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
2f630 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2f640 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
2f650 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2f660 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2f670 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2f680 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2f690 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2f6a0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2f6b0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2f6c0 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
2f6d0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2f6e0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2f6f0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
2f700 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2f710 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2f720 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2f730 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
2f740 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2f750 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2f760 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2f770 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
2f780 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
2f790 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
2f7a0 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
2f7b0 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
2f7c0 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
2f7d0 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
2f7e0 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
2f7f0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
2f800 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
2f810 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
2f820 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
2f830 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
2f840 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
2f850 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
2f860 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
2f870 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
2f880 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
2f890 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
2f8a0 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
2f8b0 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
2f8c0 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
2f8d0 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
2f8e0 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
2f8f0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
2f900 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
2f910 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
2f920 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
2f930 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
2f940 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2f950 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
2f960 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
2f970 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
2f980 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2f990 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
2f9a0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2f9b0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2f9c0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2f9d0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2f9e0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2f9f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2fa00 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2fa10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2fa20 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
2fa30 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2fa40 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
2fa50 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
2fa60 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
2fa70 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
2fa80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2fa90 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
2faa0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
2fab0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2fac0 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
2fad0 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
2fae0 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
2faf0 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
2fb00 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
2fb10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2fb20 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
2fb30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2fb40 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
2fb50 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
2fb60 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
2fb70 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
2fb80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2fb90 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2fba0 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
2fbb0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
2fbc0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2fbd0 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
2fbe0 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
2fbf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2fc00 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
2fc10 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2fc20 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
2fc30 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
2fc40 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
2fc50 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
2fc60 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
2fc70 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
2fc80 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
2fc90 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
2fca0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2fcb0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2fcc0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2fcd0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
2fce0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
2fcf0 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
2fd00 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
2fd10 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
2fd20 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
2fd30 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
2fd40 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
2fd50 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
2fd60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fd70 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2fd80 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
2fd90 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
2fda0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2fdb0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
2fdc0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2fdd0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
2fde0 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
2fdf0 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
2fe00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
2fe10 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
2fe20 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
2fe30 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
2fe40 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
2fe50 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
2fe60 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2fe70 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
2fe80 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
2fe90 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
2fea0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
2feb0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
2fec0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
2fed0 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e  NOMEM].)^.*/.con
2fee0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2fef0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
2ff00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2ff10 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2ff20 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ff30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ff40 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2ff50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ff60 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
2ff70 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
2ff80 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
2ff90 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
2ffa0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2ffb0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2ffc0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
2ffd0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2ffe0 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
2fff0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
30000 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
30010 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
30020 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
30030 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
30040 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
30050 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
30060 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
30070 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
30080 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
30090 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
300a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
300b0 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
300c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
300d0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
300e0 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
300f0 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
30100 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
30110 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30120 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
30130 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
30140 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54   Object.**.** ^T
30150 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
30160 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
30170 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
30180 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
30190 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
301a0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
301b0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
301c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
301d0 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
301e0 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
301f0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
30200 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
30210 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
30220 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
30230 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
30240 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
30250 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
30260 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
30270 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
30280 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
30290 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
302a0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
302b0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
302c0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
302d0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
302e0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
302f0 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
30300 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
30310 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
30320 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
30330 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
30340 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
30350 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
30360 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
30370 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
30380 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
30390 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
303a0 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
303b0 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
303c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
303d0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
303e0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
303f0 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
30400 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
30410 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
30420 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
30430 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
30440 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
30450 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
30460 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
30470 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
30480 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
30490 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
304a0 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
304b0 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
304c0 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
304d0 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
304e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
304f0 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
30500 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
30510 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
30520 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
30530 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
30540 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
30550 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
30560 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
30570 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
30580 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
30590 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
305a0 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
305b0 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
305c0 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
305d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
305e0 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
305f0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
30600 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
30610 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
30620 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
30630 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
30640 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
30650 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
30660 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
30670 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
30680 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
30690 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
306a0 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
306b0 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
306c0 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
306d0 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
306e0 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
306f0 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
30700 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
30710 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
30720 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
30730 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
30740 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
30750 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
30760 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
30770 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
30780 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
30790 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
307a0 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
307b0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
307c0 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
307d0 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
307e0 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
307f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
30800 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
30810 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
30820 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
30830 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30840 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
30850 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
30860 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
30870 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
30880 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
30890 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
308a0 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
308b0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
308c0 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
308d0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
308e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
308f0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
30900 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
30910 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
30920 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30930 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
30940 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
30950 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
30960 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
30970 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
30980 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
30990 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
309a0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
309b0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
309c0 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
309d0 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
309e0 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
309f0 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
30a00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
30a10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
30a20 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
30a30 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
30a40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
30a50 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
30a60 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
30a70 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
30a80 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
30a90 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
30aa0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
30ab0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
30ac0 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
30ad0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
30ae0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
30af0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e  nctions}.**.** ^
30b00 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
30b10 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
30b20 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
30b30 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
30b40 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
30b50 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
30b60 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
30b70 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
30b80 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
30b90 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
30ba0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
30bb0 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
30bc0 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
30bd0 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
30be0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
30bf0 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
30c00 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
30c10 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
30c20 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
30c30 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
30c40 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
30c50 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
30c60 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
30c70 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
30c80 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
30c90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
30ca0 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
30cb0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
30cc0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
30cd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30ce0 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
30cf0 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
30d00 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
30d10 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
30d20 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
30d30 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
30d40 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
30d50 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
30d60 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
30d70 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
30d80 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
30d90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30da0 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
30db0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
30dc0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
30dd0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
30de0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
30df0 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
30e00 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
30e10 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
30e20 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
30e30 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
30e40 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
30e50 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
30e60 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
30e70 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
30e80 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
30e90 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
30ea0 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
30eb0 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
30ec0 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
30ed0 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
30ee0 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
30ef0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
30f00 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
30f10 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
30f20 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
30f30 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
30f40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
30f50 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
30f60 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
30f70 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
30f80 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
30f90 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
30fa0 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
30fb0 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
30fc0 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
30fd0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
30fe0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
30ff0 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
31000 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
31010 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
31020 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
31030 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
31040 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
31050 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
31060 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
31070 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
31080 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
31090 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
310a0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
310b0 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
310c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
310d0 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
310e0 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
310f0 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
31100 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
31110 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
31120 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
31130 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
31140 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70  ameters.  The ap
31150 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
31160 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65   set this parame
31170 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ter to.** [SQLIT
31180 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68  E_UTF16LE] if th
31190 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
311a0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
311b0 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  s .** [sqlite3_v
311c0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d  alue_text16le()]
311d0 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
311e0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
311f0 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  ] if the.** impl
31200 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
31210 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  es [sqlite3_valu
31220 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e  e_text16be()] on
31230 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a   an input, or.**
31240 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
31250 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  if [sqlite3_valu
31260 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75  e_text16()] is u
31270 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  sed, or [SQLITE_
31280 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69  UTF8].** otherwi
31290 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53  se.  ^The same S
312a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  QL function may 
312b0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
312c0 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69  ltiple times usi
312d0 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20  ng.** different 
312e0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
312f0 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64  ncodings, with d
31300 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65  ifferent impleme
31310 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20  ntations for.** 
31320 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  each encoding..*
31330 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
31340 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
31350 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
31360 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
31370 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
31380 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
31390 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
313a0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
313b0 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
313c0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  on..**.** ^The f
313d0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
313e0 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62  may optionally b
313f0 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c  e ORed with [SQL
31400 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
31410 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  C].** to signal 
31420 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f  that the functio
31430 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  n will always re
31440 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65  turn the same re
31450 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68  sult given.** th
31460 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69  e same inputs wi
31470 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51  thin a single SQ
31480 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f  L statement.  Mo
31490 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  st SQL functions
314a0 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e   are.** determin
314b0 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c  istic.  The buil
314c0 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20  t-in [random()] 
314d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
314e0 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a  an example of a.
314f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ** function that
31500 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e   is not determin
31510 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69  istic.  The SQLi
31520 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  te query planner
31530 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70   is able to.** p
31540 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61  erform additiona
31550 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20  l optimizations 
31560 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  on deterministic
31570 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75   functions, so u
31580 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51  se.** of the [SQ
31590 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
315a0 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f  IC] flag is reco
315b0 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f  mmended where po
315c0 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ssible..**.** ^(
315d0 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
315e0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
315f0 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
31600 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
31610 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
31620 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
31630 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
31640 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
31650 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
31660 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
31670 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
31680 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
31690 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
316a0 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
316b0 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
316c0 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
316d0 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
316e0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
316f0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
31700 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
31710 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
31720 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
31730 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
31740 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
31750 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
31760 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
31770 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
31780 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
31790 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
317a0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
317b0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
317c0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
317d0 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
317e0 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
317f0 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
31800 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
31810 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
31820 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
31830 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
31840 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
31850 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
31860 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
31870 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
31880 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
31890 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
318a0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
318b0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
318c0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
318d0 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
318e0 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
318f0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
31900 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
31910 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
31920 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
31930 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
31940 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
31950 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
31960 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
31970 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31980 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
31990 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
319a0 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
319b0 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
319c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
319d0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
319e0 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
319f0 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
31a00 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
31a10 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
31a20 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
31a30 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
31a40 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
31a50 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
31a60 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
31a70 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
31a80 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
31a90 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
31aa0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31ab0 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
31ac0 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
31ad0 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
31ae0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
31af0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
31b00 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
31b10 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
31b20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
31b30 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
31b40 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
31b50 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
31b60 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
31b70 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
31b80 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
31b90 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
31ba0 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
31bb0 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
31bc0 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
31bd0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
31be0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
31bf0 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
31c00 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
31c10 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
31c20 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
31c30 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
31c40 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
31c50 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
31c60 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
31c70 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
31c80 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
31c90 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
31ca0 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
31cb0 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
31cc0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
31cd0 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
31ce0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
31cf0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
31d00 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
31d10 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
31d20 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
31d30 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
31d40 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
31d50 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
31d60 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
31d70 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
31d80 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
31d90 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
31da0 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
31db0 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
31dc0 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
31dd0 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
31de0 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
31df0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
31e00 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
31e10 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
31e20 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
31e30 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
31e40 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
31e50 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
31e60 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
31e70 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
31e80 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
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 6e 6f 72 20 66 69 6e 61  nection nor fina
31eb0 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
31ec0 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
31ed0 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
31ee0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
31ef0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
31f00 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31f10 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
31f20 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
31f30 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
31f40 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
31f50 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
31f60 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
31f70 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
31f80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31f90 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
31fa0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
31fb0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
31fc0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
31fd0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
31fe0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
31ff0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32000 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
32010 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
32020 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
32030 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
32040 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
32050 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
32060 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
32070 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
32080 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
32090 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
320a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
320b0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
320c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
320d0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
320e0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
320f0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
32100 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
32110 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32120 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
32130 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
32140 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
32150 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
32160 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
32170 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
32180 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
32190 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
321a0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
321b0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
321c0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
321d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
321e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
321f0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
32200 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
32210 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
32220 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
32230 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32240 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
32250 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
32260 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
32270 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
32280 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
32290 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
322a0 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
322b0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
322c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
322d0 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20  TF8           1 
322e0 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35     /* IMP: R-375
322f0 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66  14-35566 */.#def
32300 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
32310 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f  LE        2    /
32320 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33  * IMP: R-03371-3
32330 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20  7637 */.#define 
32340 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
32350 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d        3    /* IM
32360 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34  P: R-51971-34154
32370 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
32380 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
32390 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
323a0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
323b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
323c0 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
323d0 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61   5    /* Depreca
323e0 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ted */.#define S
323f0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
32400 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
32410 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
32420 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
32430 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
32440 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a  unction Flags.**
32450 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
32460 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20  nts may be ORed 
32470 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68  together with th
32480 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  e .** [SQLITE_UT
32490 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74  F8 | preferred t
324a0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73  ext encoding] as
324b0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
324c0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ment.** to [sqli
324d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
324e0 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
324f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32500 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
32510 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32520 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ction_v2()]..*/.
32530 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
32540 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20  ETERMINISTIC    
32550 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  0x800../*.** CAP
32560 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
32570 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
32580 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
32590 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
325a0 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
325b0 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
325c0 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
325d0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
325e0 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
325f0 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
32600 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
32610 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
32620 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
32630 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
32640 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
32650 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
32660 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
32670 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
32680 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
32690 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
326a0 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
326b0 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
326c0 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
326d0 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
326e0 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
326f0 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
32700 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
32710 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
32720 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32730 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
32740 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
32750 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
32760 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
32770 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
32780 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
32790 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
327a0 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
327b0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
327c0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
327d0 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
327e0 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
327f0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
32800 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
32810 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
32820 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
32830 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
32840 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
32850 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
32860 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20  e3_int64,int),. 
32870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32880 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74       void*,sqlit
32890 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
328a0 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
328b0 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
328c0 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
328d0 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a  ter Values.**.**
328e0 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
328f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
32900 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
32910 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
32920 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
32930 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
32940 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
32950 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
32960 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
32970 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
32980 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
32990 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
329a0 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
329b0 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
329c0 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
329d0 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
329e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
329f0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
32a00 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32a10 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
32a20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
32a30 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
32a40 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
32a50 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
32a60 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
32a70 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
32a80 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
32a90 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
32aa0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
32ab0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32ac0 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
32ad0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
32ae0 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
32af0 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
32b00 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
32b10 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
32b20 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
32b30 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
32b40 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
32b50 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32b60 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
32b70 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
32b80 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
32b90 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32ba0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
32bb0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
32bc0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
32bd0 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
32be0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32bf0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
32c00 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
32c10 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
32c20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
32c30 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
32c40 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
32c50 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  g [column access
32c60 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65   functions].** e
32c70 78 63 65 70 74 20 74 68 61 74 20 74 68 65 73 65  xcept that these
32c80 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
32c90 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
32ca0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32cb0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
32cc0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
32cd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
32ce0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
32cf0 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
32d00 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  umber..**.** ^Th
32d10 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
32d20 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
32d30 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
32d40 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
32d50 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
32d60 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
32d70 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54  ost machine.  ^T
32d80 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
32d90 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
32da0 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
32db0 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
32dc0 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
32dd0 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73  t UTF-16 strings
32de0 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
32df0 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
32e00 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
32e10 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
32e20 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
32e30 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
32e40 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
32e50 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
32e60 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
32e70 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
32e80 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
32e90 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
32ea0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
32eb0 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
32ec0 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
32ed0 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
32ee0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
32ef0 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
32f00 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
32f10 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
32f20 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
32f30 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
32f40 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
32f50 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
32f60 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
32f70 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
32f80 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
32f90 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
32fa0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
32fb0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
32fc0 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
32fd0 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
32fe0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  .)^.**.** Please
32ff0 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
33000 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
33010 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
33020 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
33030 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
33040 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
33050 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
33060 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
33070 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
33080 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
33090 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
330a0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
330b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
330c0 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
330d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
330e0 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
330f0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
33100 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
33110 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
33120 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
33130 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
33140 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
33150 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
33160 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
33170 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
33180 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
33190 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
331a0 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
331b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
331c0 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
331d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
331e0 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
331f0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
33200 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
33210 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
33220 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
33230 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
33240 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
33250 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
33260 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
33270 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
33280 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
33290 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
332a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
332b0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
332c0 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
332d0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
332e0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
332f0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
33300 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
33310 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
33320 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
33330 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
33340 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
33350 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
33360 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
33370 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33380 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
33390 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
333a0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
333b0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
333c0 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
333d0 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
333e0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
333f0 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
33400 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  ion Context.**.*
33410 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * Implementation
33420 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  s of aggregate S
33430 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
33440 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
33450 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
33460 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ory for storing 
33470 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
33480 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
33490 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
334a0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
334b0 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73  (C,N) routine is
334c0 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20   called .** for 
334d0 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
334e0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c  regate function,
334f0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63   SQLite.** alloc
33500 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79  ates N of memory
33510 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
33520 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
33530 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
33540 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65  ** to the new me
33550 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64  mory. ^On second
33560 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
33570 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
33580 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
33590 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
335a0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
335b0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
335c0 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
335d0 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
335e0 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65  .  Sqlite3_aggre
335f0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69  gate_context() i
33600 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61  s normally.** ca
33610 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  lled once for ea
33620 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ch invocation of
33630 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62   the xStep callb
33640 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65  ack and then one
33650 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68  .** last time wh
33660 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  en the xFinal ca
33670 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
33680 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f  d.  ^(When no ro
33690 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61  ws match.** an a
336a0 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20  ggregate query, 
336b0 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c  the xStep() call
336c0 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72  back of the aggr
336d0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  egate function.*
336e0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
336f0 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64   is never called
33700 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73   and xFinal() is
33710 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20   called exactly 
33720 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73  once..** In thos
33730 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33  e cases, sqlite3
33740 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
33750 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61  xt() might be ca
33760 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
33770 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20  first time from 
33780 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e  within xFinal().
33790 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
337a0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
337b0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
337c0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
337d0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20  ULL pointer .** 
337e0 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65  when first calle
337f0 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74  d if N is less t
33800 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
33810 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d  zero or if a mem
33820 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20  ory.** allocate 
33830 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
33840 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
33850 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
33860 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
33870 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
33880 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
33890 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
338a0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
338b0 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
338c0 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
338d0 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
338e0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
338f0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
33900 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33910 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
33920 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
33930 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
33940 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
33950 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
33960 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69  llocation.)^  Wi
33970 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  thin the xFinal 
33980 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20  callback, it is 
33990 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74  customary to set
339a0 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73  .** N=0 in calls
339b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
339c0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
339d0 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a  N) so that no .*
339e0 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f  * pointless memo
339f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f  ry allocations o
33a00 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ccur..**.** ^SQL
33a10 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
33a20 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f  y frees the memo
33a30 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
33a40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
33a50 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
33a60 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
33a70 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  te query conclud
33a80 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
33a90 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  rst parameter mu
33aa0 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  st be a copy of 
33ab0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
33ac0 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
33ad0 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
33ae0 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
33af0 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  t parameter.** t
33b00 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78  o the xStep or x
33b10 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72  Final callback r
33b20 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
33b30 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
33b40 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
33b50 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
33b60 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
33b70 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
33b80 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
33b90 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
33ba0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
33bb0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
33bc0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
33bd0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
33be0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33bf0 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
33c00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
33c10 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
33c20 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
33c30 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
33c40 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
33c50 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
33c60 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
33c70 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
33c80 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
33c90 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
33ca0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
33cb0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33cc0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
33cd0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
33ce0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
33cf0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
33d00 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
33d10 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
33d20 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
33d30 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
33d40 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
33d50 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
33d60 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
33d70 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
33d80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33d90 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
33da0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
33db0 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
33dc0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
33dd0 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
33de0 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
33df0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
33e00 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
33e10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
33e20 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
33e30 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
33e40 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
33e50 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
33e60 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
33e70 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
33e80 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
33e90 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
33ea0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33eb0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
33ec0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33ed0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
33ee0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
33ef0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
33f00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
33f10 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33f20 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
33f30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
33f40 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
33f50 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
33f60 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
33f70 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
33f80 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ata.**.** These 
33f90 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
33fa0 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67   used by (non-ag
33fb0 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e  gregate) SQL fun
33fc0 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
33fd0 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
33fe0 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
33ff0 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
34000 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
34010 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
34020 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
34030 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
34040 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
34050 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
34060 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
34070 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
34080 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
34090 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
340a0 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a  ed.  An example.
340b0 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73  ** of where this
340c0 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c   might be useful
340d0 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72   is in a regular
340e0 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
340f0 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  hing.** function
34100 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
34110 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
34120 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
34130 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61   can be stored a
34140 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
34150 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
34160 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  e pattern string
34170 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c  .  .** Then as l
34180 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65  ong as the patte
34190 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e  rn string remain
341a0 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74  s the same,.** t
341b0 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
341c0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
341d0 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
341e0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
341f0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
34200 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ame function..**
34210 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34220 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
34230 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
34240 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
34250 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
34260 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
34270 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
34280 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
34290 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
342a0 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
342b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
342c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
342d0 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  n. ^If there is 
342e0 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  no metadata.** a
342f0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
34300 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  he function argu
34310 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74  ment, this sqlit
34320 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
34330 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
34340 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
34350 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
34360 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
34370 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e  data(C,N,P,X) in
34380 74 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20  terface saves P 
34390 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  as metadata for 
343a0 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
343b0 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
343c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
343d0 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73  function.  ^Subs
343e0 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
343f0 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
34400 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75  uxdata(C,N) retu
34410 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f  rn P from the mo
34420 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c  st recent.** sql
34430 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
34440 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69  (C,N,P,X) call i
34450 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  f the metadata i
34460 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72  s still valid or
34470 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20  .** NULL if the 
34480 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
34490 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  n discarded..** 
344a0 5e 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c  ^After each call
344b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
344c0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
344d0 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20   where X is not 
344e0 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  NULL,.** SQLite 
344f0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
34500 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
34510 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d  ion X with param
34520 65 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a  eter P exactly.*
34530 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65  * once, when the
34540 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 73   metadata is dis
34550 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74  carded..** SQLit
34560 65 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 73  e is free to dis
34570 63 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 74  card the metadat
34580 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69  a at any time, i
34590 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a  ncluding: <ul>.*
345a0 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20  * <li> when the 
345b0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
345c0 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
345d0 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20   changes, or.** 
345e0 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74  <li> when [sqlit
345f0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
34600 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34610 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f  ()] is called fo
34620 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51  r the.**      SQ
34630 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a  L statement, or.
34640 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c  ** <li> when sql
34650 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
34660 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67  () is invoked ag
34670 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ain on the same 
34680 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a  parameter, or.**
34690 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65   <li> during the
346a0 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65   original sqlite
346b0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
346c0 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f  call when a memo
346d0 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f  ry .**      allo
346e0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
346f0 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  urs. </ul>)^.**.
34700 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74  ** Note the last
34710 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69   bullet in parti
34720 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74  cular.  The dest
34730 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20  ructor X in .** 
34740 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
34750 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67  ata(C,N,P,X) mig
34760 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d  ht be called imm
34770 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
34780 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
34790 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
347a0 74 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74  terface even ret
347b0 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c  urns.  Hence sql
347c0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
347d0 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  ().** should be 
347e0 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20  called near the 
347f0 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74  end of the funct
34800 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
34810 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75  on and the.** fu
34820 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
34830 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
34840 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66   make any use of
34850 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69   P after.** sqli
34860 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
34870 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ) has been calle
34880 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72  d..**.** ^(In pr
34890 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61  actice, metadata
348a0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
348b0 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
348c0 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63  alls for.** func
348d0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tion parameters 
348e0 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65  that are compile
348f0 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c  -time constants,
34900 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72   including liter
34910 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
34920 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e   [parameters] an
34930 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f  d expressions co
34940 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20  mposed from the 
34950 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  same.)^.**.** Th
34960 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
34970 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
34980 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
34990 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
349a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
349b0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
349c0 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
349d0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
349e0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
349f0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
34a00 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
34a10 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
34a20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
34a30 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
34a40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
34a50 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
34a60 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
34a70 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
34a80 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
34a90 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
34aa0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
34ab0 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
34ac0 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
34ad0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
34ae0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
34af0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
34b00 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
34b10 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
34b20 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
34b30 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
34b40 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
34b50 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
34b60 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
34b70 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
34b80 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
34b90 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
34ba0 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
34bb0 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
34bc0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
34bd0 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
34be0 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
34bf0 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
34c00 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
34c10 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
34c20 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
34c30 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
34c40 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
34c50 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
34c60 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
34c70 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
34c80 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
34c90 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
34ca0 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70  ompilers..*/.typ
34cb0 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
34cc0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
34cd0 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
34ce0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
34cf0 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
34d00 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
34d10 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
34d20 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
34d30 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
34d40 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
34d50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
34d60 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
34d70 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
34d80 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tion.**.** These
34d90 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
34da0 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
34db0 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
34dc0 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
34dd0 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
34de0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
34df0 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
34e00 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34e10 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
34e20 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34e30 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
34e40 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
34e50 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
34e60 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
34e70 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
34e80 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
34e90 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
34ea0 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
34eb0 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
34ec0 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
34ed0 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
34ee0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
34ef0 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
34f00 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
34f10 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
34f20 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
34f30 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
34f40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
34f50 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
34f60 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
34f70 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
34f80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34f90 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
34fa0 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
34fb0 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
34fc0 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
34fd0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
34fe0 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
34ff0 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
35000 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
35010 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
35020 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35030 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
35040 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
35050 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
35060 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
35070 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35080 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
35090 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
350a0 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
350b0 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
350c0 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
350d0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
350e0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
350f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35100 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
35110 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
35120 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
35130 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
35140 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35150 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
35160 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
35170 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
35180 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
35190 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
351a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
351b0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
351c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
351d0 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
351e0 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
351f0 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
35200 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
35210 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53  exception..** ^S
35220 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
35230 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
35240 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
35250 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
35260 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35270 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
35280 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
35290 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
352a0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
352b0 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65  e.  ^SQLite inte
352c0 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
352d0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
352e0 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
352f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
35300 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65  s UTF-8. ^SQLite
35310 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
35320 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
35330 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35340 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
35350 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
35360 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20  yte order.  ^If 
35370 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
35380 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
35390 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
353a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
353b0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
353c0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
353d0 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
353e0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
353f0 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
35400 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
35410 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
35420 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
35430 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
35440 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35450 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
35460 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35470 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
35480 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
35490 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
354a0 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
354b0 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
354c0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
354d0 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
354e0 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20  essage..** ^The 
354f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35500 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
35510 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
35520 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
35530 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
35540 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
35550 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
35560 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
35570 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
35580 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
35590 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
355a0 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
355b0 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
355c0 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
355d0 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73   harm..** ^The s
355e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
355f0 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
35600 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
35610 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
35620 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
35630 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
35640 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
35650 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66  nction.  ^By def
35660 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
35670 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
35680 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62  E_ERROR.  ^A sub
35690 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
356a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
356b0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
356c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
356d0 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
356e0 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
356f0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
35700 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35710 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
35720 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
35730 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
35740 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
35750 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
35760 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
35770 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
35780 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
35790 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
357a0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
357b0 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20  mem() interface 
357c0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
357d0 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
357e0 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
357f0 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  at a memory allo
35800 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
35810 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35820 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
35830 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
35840 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
35850 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
35860 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35870 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
35880 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
35890 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
358a0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
358b0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
358c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
358d0 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
358e0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
358f0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
35900 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
35910 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
35920 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
35930 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
35940 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
35950 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
35960 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
35970 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
35980 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
35990 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
359a0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
359b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
359c0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
359d0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e NULL..**.** ^T
359e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
359f0 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
35a00 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
35a10 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  ),.** sqlite3_re
35a20 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
35a30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
35a40 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
35a50 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
35a60 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
35a70 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
35a80 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35a90 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
35aa0 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
35ab0 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
35ac0 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
35ad0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
35ae0 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
35af0 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
35b00 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
35b10 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
35b20 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  y..** ^The sqlit
35b30 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34  e3_result_text64
35b40 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
35b50 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
35b60 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70 70 6c  ue of an.** appl
35b70 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35b80 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
35b90 20 74 65 78 74 20 73 74 72 69 6e 67 20 69 6e 20   text string in 
35ba0 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73  an encoding.** s
35bb0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
35bc0 66 69 66 74 68 20 28 61 6e 64 20 6c 61 73 74 29  fifth (and last)
35bd0 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63   parameter, whic
35be0 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a 2a 2a  h must be one.**
35bf0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
35c00 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
35c10 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
35c20 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  BE], or [SQLITE_
35c30 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51  UTF16LE]..** ^SQ
35c40 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
35c50 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
35c60 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
35c70 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
35c80 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
35c90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35ca0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
35cb0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
35cc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
35cd0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35ce0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
35cf0 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
35d00 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
35d10 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
35d20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
35d30 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
35d40 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
35d50 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
35d60 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
35d70 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
35d80 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
35d90 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
35da0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
35db0 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
35dc0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
35dd0 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
35de0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
35df0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
35e00 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
35e10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
35e20 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
35e30 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20  ion result.  If 
35e40 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
35e50 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  r is non-negativ
35e60 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75  e, then it.** mu
35e70 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
35e80 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73  ffset into the s
35e90 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20  tring where the 
35ea0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
35eb0 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69  ould.** appear i
35ec0 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  f the string whe
35ed0 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65  re NUL terminate
35ee0 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
35ef0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a  haracters occur.
35f00 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  ** in the string
35f10 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65   at a byte offse
35f20 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74  t that is less t
35f30 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  han the value of
35f40 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61   the 3rd.** para
35f50 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
35f60 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
35f70 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d   will contain em
35f80 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20  bedded NULs and 
35f90 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66  the.** result of
35fa0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65   expressions ope
35fb0 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67  rating on string
35fc0 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  s with embedded 
35fd0 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
35fe0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  d..** ^If the 4t
35ff0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
36000 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36010 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
36020 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
36030 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
36040 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
36050 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
36060 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
36070 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
36080 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
36090 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
360a0 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
360b0 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
360c0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
360d0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
360e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
360f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
36100 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
36110 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
36120 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
36130 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
36140 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
36150 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
36160 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
36170 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
36180 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
36190 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
361a0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
361b0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
361c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
361d0 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
361e0 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
361f0 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
36200 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
36210 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
36220 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
36230 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
36240 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36250 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
36260 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
36270 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
36280 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
36290 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
362a0 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
362b0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
362c0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
362d0 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
362e0 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
362f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
36300 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
36310 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36320 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
36330 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
36340 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
36350 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
36360 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
36370 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
36380 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
36390 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
363a0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
363b0 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
363c0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
363d0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
363e0 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
363f0 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
36400 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
36410 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
36420 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
36430 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
36440 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
36450 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
36460 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
36470 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
36480 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
36490 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
364a0 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72   harm..** ^A [pr
364b0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
364c0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
364d0 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
364e0 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
364f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
36500 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
36510 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
36520 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
36530 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
36540 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
36550 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
36560 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
36570 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
36580 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
36590 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
365a0 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
365b0 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
365c0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
365d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
365e0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
365f0 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
36600 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
36610 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
36620 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
36630 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ned..*/.void sql
36640 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
36650 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36660 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
36670 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
36680 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
36690 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 36 34  e3_result_blob64
366a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
366b0 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 0a 20  *,const void*,. 
366c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
366d0 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
366e0 33 5f 75 69 6e 74 36 34 2c 76 6f 69 64 28 2a 29  3_uint64,void(*)
366f0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
36700 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
36710 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
36720 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
36730 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36740 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
36750 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
36760 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
36770 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36780 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
36790 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
367a0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
367b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
367c0 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
367d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
367e0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
367f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
36800 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
36810 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
36820 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36830 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
36840 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
36850 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36860 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
36870 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
36880 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36890 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
368a0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
368b0 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
368c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
368d0 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
368e0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
368f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
36900 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36910 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
36920 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
36930 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
36940 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34 28 73  _result_text64(s
36950 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36960 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c   const char*,sql
36970 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
36980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36990 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
369a0 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64  void*), unsigned
369b0 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b   char encoding);
369c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
369d0 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
369e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
369f0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
36a00 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
36a10 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36a20 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
36a30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36a40 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
36a50 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
36a60 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36a70 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
36a80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36a90 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
36aa0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
36ab0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36ac0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
36ad0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
36ae0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
36af0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36b00 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
36b10 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
36b20 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
36b30 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
36b40 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
36b50 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  uences.**.** ^Th
36b60 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64  ese functions ad
36b70 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f  d, remove, or mo
36b80 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f  dify a [collatio
36b90 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  n] associated.**
36ba0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
36bb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36bc0 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
36bd0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
36be0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
36bf0 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
36c00 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  n is a UTF-8 str
36c10 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
36c20 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36c30 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
36c40 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36c50 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
36c60 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
36c70 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
36c80 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
36c90 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36ca0 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  16()..** ^Collat
36cb0 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63  ion names that c
36cc0 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63  ompare equal acc
36cd0 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74  ording to [sqlit
36ce0 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61  e3_strnicmp()] a
36cf0 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
36d00 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20   to be the same 
36d10 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  name..**.** ^(Th
36d20 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
36d30 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74   (eTextRep) must
36d40 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
36d50 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c  onstants:.** <ul
36d60 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
36d70 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e  E_UTF8],.** <li>
36d80 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
36d90 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
36da0 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
36db0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
36dc0 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  16], or.** <li> 
36dd0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
36de0 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  IGNED]..** </ul>
36df0 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74  )^.** ^The eText
36e00 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74  Rep argument det
36e10 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f  ermines the enco
36e20 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20  ding of strings 
36e30 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65  passed.** to the
36e40 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36e50 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43  ion callback, xC
36e60 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
36e70 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
36e80 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  and [SQLITE_UTF1
36e90 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
36ea0 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a  s for eTextRep.*
36eb0 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20  * force strings 
36ec0 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68  to be UTF16 with
36ed0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
36ee0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  er..** ^The [SQL
36ef0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
36f00 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65  D] value for eTe
36f10 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72  xtRep forces str
36f20 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a  ings to begin.**
36f30 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65   on an even byte
36f40 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20   address..**.** 
36f50 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75  ^The fourth argu
36f60 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61  ment, pArg, is a
36f70 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  n application da
36f80 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ta pointer that 
36f90 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72  is passed.** thr
36fa0 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
36fb0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
36fc0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
36fd0 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  tion callback..*
36fe0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
36ff0 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62  argument, xCallb
37000 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65  ack, is a pointe
37010 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  r to the collati
37020 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ng function..** 
37030 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74  ^Multiple collat
37040 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61  ing functions ca
37050 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
37060 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  using the same n
37070 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20  ame but.** with 
37080 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
37090 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e  ep parameters an
370a0 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  d SQLite will us
370b0 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66  e whichever.** f
370c0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
370d0 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
370e0 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66  t of data transf
370f0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  ormation..** ^If
37100 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61   the xCallback a
37110 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20  rgument is NULL 
37120 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  then the collati
37130 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  ng function is.*
37140 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65  * deleted.  ^Whe
37150 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20  n all collating 
37160 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67  functions having
37170 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61   the same name a
37180 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74  re deleted,.** t
37190 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  hat collation is
371a0 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c   no longer usabl
371b0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f  e..**.** ^The co
371c0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
371d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
371e0 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79  oked with a copy
371f0 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a   of the pArg .**
37200 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
37210 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69  a pointer and wi
37220 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69  th two strings i
37230 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  n the encoding s
37240 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
37250 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
37260 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61  ment.  The colla
37270 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
37280 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20  st return an.** 
37290 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20  integer that is 
372a0 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20  negative, zero, 
372b0 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69  or positive.** i
372c0 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
372d0 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
372e0 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
372f0 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
37300 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63  econd,.** respec
37310 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61  tively.  A colla
37320 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
37330 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  st always return
37340 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72   the same answer
37350 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61  .** given the sa
37360 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74  me inputs.  If t
37370 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61  wo or more colla
37380 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
37390 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a  re registered.**
373a0 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   to the same col
373b0 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69  lation name (usi
373c0 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  ng different eTe
373d0 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68  xtRep values) th
373e0 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67  en all.** must g
373f0 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e  ive an equivalen
37400 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e  t answer when in
37410 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76  voked with equiv
37420 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a  alent strings..*
37430 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * The collating 
37440 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62  function must ob
37450 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ey the following
37460 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20   properties for 
37470 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41  all.** strings A
37480 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a  , B, and C:.**.*
37490 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49  * <ol>.** <li> I
374a0 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41  f A==B then B==A
374b0 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  ..** <li> If A==
374c0 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20  B and B==C then 
374d0 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  A==C..** <li> If
374e0 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67   A&lt;B THEN B&g
374f0 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  t;A..** <li> If 
37500 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b  A&lt;B and B&lt;
37510 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a  C then A&lt;C..*
37520 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </ol>.**.** If
37530 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   a collating fun
37540 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20  ction fails any 
37550 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e  of the above con
37560 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61  straints and tha
37570 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66  t.** collating f
37580 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69  unction is  regi
37590 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c  stered and used,
375a0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
375b0 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
375c0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
375d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
375e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
375f0 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
37600 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
37610 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
37620 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f  with the additio
37630 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74  n that the xDest
37640 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
37650 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20  invoked on pArg 
37660 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c  when.** the coll
37670 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
37680 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43  s deleted..** ^C
37690 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
376a0 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77  ns are deleted w
376b0 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
376c0 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
376d0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  .** calls to the
376e0 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
376f0 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
37700 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61   when the.** [da
37710 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37720 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69  n] is closed usi
37730 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
37740 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  e()]..**.** ^The
37750 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
37760 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e  ck is <u>not</u>
37770 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a   called if the .
37780 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
37790 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
377a0 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e   function fails.
377b0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
377c0 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  hat invoke.** sq
377d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
377e0 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68  lation_v2() with
377f0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73   a non-NULL xDes
37800 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68  troy argument sh
37810 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74  ould .** check t
37820 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61  he return code a
37830 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  nd dispose of th
37840 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
37850 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  ta pointer.** th
37860 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20  emselves rather 
37870 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53  than expecting S
37880 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69  QLite to deal wi
37890 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a  th it for them..
378a0 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65  ** This is diffe
378b0 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20  rent from every 
378c0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
378d0 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63  erface.  The inc
378e0 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69  onsistency .** i
378f0 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75  s unfortunate bu
37900 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  t cannot be chan
37910 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  ged without brea
37920 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a  king backwards .
37930 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
37940 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
37950 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
37960 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
37970 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
37980 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
37990 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
379a0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
379b0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
379c0 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
379d0 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
379e0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
379f0 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
37a00 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
37a10 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
37a20 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
37a30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
37a40 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
37a50 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
37a60 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
37a70 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
37a80 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
37a90 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
37aa0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
37ab0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
37ac0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
37ad0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
37ae0 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
37af0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37b00 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  lation16(.  sqli
37b10 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76  te3*, .  const v
37b20 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e  oid *zName,.  in
37b30 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
37b40 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
37b50 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
37b60 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
37b70 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
37b80 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
37b90 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
37ba0 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
37bb0 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69  s.**.** ^To avoi
37bc0 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
37bd0 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
37be0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
37bf0 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
37c00 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
37c10 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
37c20 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
37c30 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
37c40 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
37c50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
37c60 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
37c70 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
37c80 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
37c90 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
37ca0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  red..**.** ^If t
37cb0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
37cc0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
37cd0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
37ce0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
37cf0 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
37d00 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
37d10 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
37d20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
37d30 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
37d40 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
37d50 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  -8. ^If sqlite3_
37d60 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37d70 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
37d80 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
37d90 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
37da0 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
37db0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
37dc0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68   ^A call to eith
37dd0 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
37de0 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e  aces the existin
37df0 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64  g collation-need
37e00 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ed callback..**.
37e10 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61  ** ^(When the ca
37e20 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
37e30 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
37e40 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
37e50 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
37e60 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
37e70 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
37e80 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
37e90 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
37ea0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
37eb0 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
37ec0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
37ed0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
37ee0 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
37ef0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
37f00 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
37f10 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
37f20 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
37f30 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
37f40 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
37f50 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
37f60 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
37f70 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
37f80 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
37f90 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
37fa0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
37fb0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
37fc0 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
37fd0 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a  sequence.)^.**.*
37fe0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
37ff0 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
38000 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
38010 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
38020 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
38030 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
38040 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
38050 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
38060 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
38070 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
38080 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69  tion_v2()]..*/.i
38090 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
380a0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73  tion_needed(.  s
380b0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
380c0 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
380d0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
380e0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
380f0 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  char*).);.int sq
38100 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
38110 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
38120 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
38130 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
38140 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
38150 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
38160 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51  *).);..#ifdef SQ
38170 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f  LITE_HAS_CODEC./
38180 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
38190 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
381a0 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
381b0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
381c0 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
381d0 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
381e0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
381f0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
38200 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
38210 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
38220 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
38230 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
38240 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
38250 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
38260 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
38270 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
38280 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
38290 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
382a0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
382b0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
382c0 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20  e key */.);.int 
382d0 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a  sqlite3_key_v2(.
382e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
382f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38300 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
38310 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
38320 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
38330 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f  ame,           /
38340 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  * Name of the da
38350 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
38360 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
38370 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
38380 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
38390 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
383a0 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
383b0 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
383c0 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
383d0 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
383e0 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
383f0 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
38400 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
38410 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
38420 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
38430 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
38440 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
38450 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
38460 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
38470 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
38480 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
38490 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
384a0 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
384b0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
384c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
384d0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
384e0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
384f0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
38500 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
38510 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74  ew key */.);.int
38520 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76   sqlite3_rekey_v
38530 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
38540 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
38550 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
38560 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
38570 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
38580 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  DbName,         
38590 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
385a0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
385b0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
385c0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
385d0 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
385e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
385f0 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
38600 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64   key for a SEE d
38610 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
38620 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
38630 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20  none of the SEE 
38640 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
38650 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
38660 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65  te3_activate_see
38670 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
38680 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
38690 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
386a0 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
386b0 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c  ndif..#ifdef SQL
386c0 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44  ITE_ENABLE_CEROD
386d0 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
386e0 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
386f0 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61  y for a CEROD da
38700 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
38710 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
38720 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44  one of the CEROD
38730 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
38740 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ork..*/.void sql
38750 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65  ite3_activate_ce
38760 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  rod(.  const cha
38770 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
38780 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
38790 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
387a0 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
387b0 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64  API3REF: Suspend
387c0 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41   Execution For A
387d0 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a   Short Time.**.*
387e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c  * The sqlite3_sl
387f0 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
38800 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
38810 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
38820 65 6e 64 20 65 78 6